bncs_csi

DDS BNCS Control System Interface: bncs_csi

Description

This is a technology evaluation application.

Features

This application replaces "CSI32" (and its many historic variants: v3csi, v4csi etc. etc.). Whilst it's like CSI32 it's not CSI32 - every last wacky feature and nuance has not been recreated like-for-like.

Fundamental Features:

  • Client and driver support
  • Normal messaging device messaging (i.e. commands and "revertives")
  • BNCS "Database" support
  • both IPC mechanisms (BBC_COPYDATA and WM_COPYDATA)
  • driver redundancy switching
  • Configurable external DDS quality of service settings file
  • extended device/index ranges to the maximum extent of the IPC messages

Notable ommissions:

  • Workstation status infodriver
  • Driver status infodriver
  • enhanced IPC for access to 32 bit device/index/database
  • direct driver messaging
  • FABIAN support (want FABIAN functionality? Use slink!)
  • BBC_NETTXRXSTATUS, BBC_NETMSGUPDATE, HWND_BROADCAST_NETSTATUSMSG, HWND_BROADCAST_CSICLOSEWARNING, HWND_BROADCAST_APPREADY messages
  • selective caching
  • multitiude of CS32 configuration options

CSI's in years gone by have been very chilled about sending some values and will accept any string whatsoever. This version however decodes, validates and sends specific messages.

Configuration/Command Line

This application does not have any configurable parameters except the following command line parameters:

Option | Value
/domain=1 | DDS domain number - this should match the domain ID in the OSPL_URI Qos file

Environment

This version requires the following environment variable:

Variable | Value
OSPL_URI | file: //<your system root>\config\dds\ospl.xml Note: This should not have a space after the file: but unfortunately this doesn't format well in these docs.

Dependencies

The following files are required in windows\lib

File | Notes
cmsoap.dll | DDS
cmxml.dll | DDS
dcpssacpp.dll | DDS
ddsi2.dll | DDS
ddskernel.dll | DDS
spliced.dll | DDS
ddsrrstorage.dll | DDS
snetworking.dll | DDS
qt5core.dll | Qt
qt5gui.dll | Qt
qt5network.dll | Qt
qt5widgets.dll | Qt
qwindows.dll | Qt (in subfolder platforms\windows)

Maximum indexes using original inter-process communications (IPC)

These are IPC limits - the bit that transfers messages about between applications on a workstation. These are not related to NetBIOS limits or those hard-coded into the CSI application.

32767 devices (1 to 32767)

This is limited by messages such as BBC_TXINFONETMSG which uses the top bit of a 16 bit value as a flag to carry extra information - so only 15 bits of unsigned value are available

65536 databases (0 to 65535)

Values are transferred as 16 bit values and all values are allowed (including database 0 of course)

65535 indexes (1 to 65535)

Values are transferred as 16 bit values throughout

32767 sources (-32767 to +32767)

Source is a signed value which limits the range

Supported Messages: external to CSI

BBC_GETHWNDCSI32, BBC_GETHWNDSHIM_ALT, BBC_GETHWNDCSI32_ALT

All handled the same, but using handleShare DLL is preferred means of getting "CSI" handle without needing to do a HWND_BROADCAST

BBC_NOTWPARAM

A simple means of seeing if this is a current CSI version

BBC_REGDEVICEID, BBC_REGDEVICEID32, BBC_DEVDRVCLOSE, BBC_UNREGDEVICEID

Driver registration

BBC_GETMAXDATABASES

Return the number of BNCS databases supported. Currently hard coded to 65536.

BBC_GETDEVTXRXMODE, BBC_SETDEVTXRXMODE

Redundancy Messages

BBC_DEVDRVREVMSG, BBC_DEVDRVPOLLMSG

Driver poll resonse - only IR, RR and GR types are supported

BBC_CACHEFLUSH, BBC_CACHETEST, BBC_CACHESWITCH, BBC_QUERYCACHEMODE, BBC_GETCACHEDDATA, BBC_GETCACHEDINDEX

Cache functions

BBC_REGCLIENT32, BBC_REGCLIENT

Handled the same to register a client

BBC_REGDEVICE, BBC_UNREGDEVICE, BBC_UNREGDEVICERANGE

"Revertive" registration functions

BBC_GETDEVPROPERTIES

String formulated to indicate databases that are avilable for the given device

BBC_TXRTRNETMSG

Free-form text message but where this implementation only messages starting "RC", "RP", "RL", "RM" are supported.

BBC_TXINFONETMSG

Free-form text message but where this implementation only messages starting "IW", "IP", "IL", "IQ" are supported.

BBC_TXGPINETMSG

Free-form text message but where this implementation only messages starting "GS", "GP", "GL" are supported.

BBC_GETDBASENAME, BBC_GETDBASEINDEX, BBC_GETDBASEINDEXEXT

Database functions

BBC_GETCSIVERSION

Hard-coded to return "2"

BBC_GETWORKSTATIONNUM

Returns workstation number

Supported Messages: CSI to external application

BBC_HWNDCSI, BBC_CSICLOSING

CSI application Messages

BBC_RXRTRNETMSG, BBC_RXINFONETMSG, BBC_RXGPINETMSG

"Revertive" messages

BBC_CLIENTMSG

Command messages

BBC_DATABASECHANGE

BBC_REQDEVGORXONLY, BBC_REQDEVGOTXRX, BBC_INQDEVGOTXRX, BBC_DEVICEIDINUSE

Redundancy messages

Logging

bncs_csi itself doesn't generate any logs.

DDS layer creates two logs in the working directory:

  • ospl-error.log
  • ospl-info.log

Upgrading to new bncs_csi releases

Use of DDS means we have to play by certain rules. When a DDS participant tries to join the party it does matching of both data types and quality of service settings. If it can't match these things because of an existing instance of bncs_csi then it will simply refuse to start up. This is just how it works.

Merely upgrading to a new BNCS v4.x release doesn't mean you'll suffer this problem - only if there are significant changes to bncs_csi which will be flagged in the release notes.

The process to upgrade has to be either take the entire system down, update and restart (not always practical of course) or alternatively update "Reserve" drivers first with them running on a new DDS domain, then update the clients, then finally update the "Main" so it's back as one system. The change of DDS domain means you're effectively running a new isolated version.

Common Error

bncs_csi requires a particular environment - specifically OSPL_URI environment variable set. If you run from workstation manager this is set by that. If you see this message:

It's entirely likely that you've tried to run bncs_csi from the command line.

You can run from the command line, but you need to have set OSPL_URI in your machine environment variables as described above. Don't forget the file: // prefix

Quality of service (QoS)/ DDS configuration

The main configuration file for the DDS layer is contained in the OSPL_URI environment variable as described above. This path is not by choice... The quality of service file itself (part of the DDS standard) is the same path but with ".qos" extension appended.

Sound words of advice

Don't fiddle with DDS configuration. In case you missed that first time: Don't fiddle with DDS configuration.

DDS doesn't just pass messages about, it defines how they're passed: how quickly, how hard to try delivering them etc. etc. When a workstation starts up it tries to join the BNCS party by subscribing to the topics that BNCS uses. To do this it ensures that it's not demanding delivery that any sender can't hope to fulfil - it does quality of service matching.

So you might be ok by changing settings to a less rigorous QoS....but on a running system you might find that all you get is an obscure DDS error message and an error log filling with largely indecipherable guff.

Don't say I didn't warn you...

Version Control

Version | Date | Author | Comments
0.0.0.1 | 07/07/2015 | DY | Development started (using RTI DDS)
0.0.0.2 |  | DY | Internal Development version
0.0.0.3 | 11/02/2016 | DY | Internal Development version
0.0.0.4 | 14/03/2016 | DY | Better behaved with aborted startups, Adds clarity to the message about USER_QOS_PROFILES.xml if one of these exists on the system and overrides our custom settings, Adds option to IPC type as to whether it should be BBC_COPYDATA messaging with type 2 messages (binary packed rather than continually pack/unpack strings
0.0.0.5 | 10/01/2017 | DY | adds domain to the command line, removes a number of debug messages
1.0.0.6 | 07/02/2017 | DY | Check of command line domain param before trying to use it. Makes a proper V1!
1.0.0.7 | 09/02/2017 | DY | adds version history file, makes app start minimised
1.0.0.8 | 05/05/2017 | DY | returns a value for BBC_GETMAXDATABASES
1.0.0.9 | 05/05/2017 | DY | DDS unexpectedly getting upset by unset string values in bncs_legacyMessage
1.0.0.10 | 29/06/2017 | DY | Fix to 1.0.0.9 to free memory used by null strings created
2.0.0.1 | 20/07/2017 | DY | First version using different DDS vendor (PrismTech)
2.0.0.2 | 24/07/2017 | DY | Some tidying, now uses handleshare DLL to save IPC lock-ups, minor changes to command line ("/domain=2" rather than just "2")
2.0.0.3 | 25/07/2017 | DY | Adds traffic counters
2.0.0.4 | 17/07/2017 | DY | Makes routerModify work again, sorts some of the mutexes, adds BBC_NOTWPARAM handling
2.0.0.5 | 01/10/2017 | DY | Restores about box and adds DDS version info (hard coded since this isn't available in DDS DLL or any API)
2.0.0.6 | 12/10/2017 | DY | Updates to V6 IPC - i.e. 32767 devices, 65535 slots - max current IPC will allow
2.0.0.7 | 17/10/2017 | DY | The first of very many instances I guess where buffers have been set to 512 bytes "because messages just are that big", except now they're not.
2.0.0.8 | 18/10/2017 | DY | Fix to wrangling of routerCrosspoint mask parameter (sloppy character set conversion)
2.0.0.9 | 19/10/2017 | DY | Parameter ordering error with routerModify. Adds flippin' obvious warning about lack of OSPL_URI instead of obscure message from DDS
2.0.0.10 | 20/10/2017 | DY | Now only distributes change of name notification if....there's a change of name - reasserting a name will not generate the notification. Also adds note in the docs about fiddling with QoS and how you deserve everything if you do.
2.0.0.11 | 24/10/2017 | DY | Router database support (for slink/fabian site linking apps to stop name changes going up own a**e)
2.0.0.12 | 24/10/2017 | DY | Sends database change message to drivers too
2.0.0.13 | 26/10/2017 | DY | anti-howlround RM commands and removes RD
2.0.0.14 | 27/10/2017 | DY | mutex hell...
2.0.0.15 | 31/10/2017 | DY | Redundancy mastering WIP
2.0.0.16 | 06/11/2017 | DY | B W C N O W U
2.0.17.0 | 21/12/2017 | DY | Corrects a long-standing misunderstanding about distribution of database change notifications. This is too all clients, not just clients with a registration for that device. Also changes 4 to 3 digit version numbering.
2.0.18.0 | 05/01/2018 | DY | Redundancy mastering reimplemented from CSI32 to allow slink to work as intended
2.0.19.0 | 09/01/2018 | DY | Net slaVe message now sends the master device as part of the message
2.0.20.0 | 09/01/2018 | DY | Adds same pragmatic fix as CSI32 to close down infodriver fix, grd fix and csi fix applications (otherwise these can get stuck running).
2.0.21.0 | 12/01/2018 | DY | Net slave command was sending the wrong master device number
2.0.22.0 | 16/01/2018 | DY | Getting redundancy state was returning the internal value of the flag, not the interface enum
2.0.23.0 | 16/01/2018 | DY | Implements max dests/sources/databases (BBC_GETMAXDESTS/BBC_GETMAXSOURCES/BBC_GETMAXSOURCENAMES/BBC_GETMAXDESTNAMES). At the point the IPC gets expanded to 4G devices/indexes then these calls are redundant anyway
2.0.24.0 | 26/01/2018 | DY | Now sets sourceWorkstation internally rather than relying on any external app to supply it (which in theory can only be the same information)
2.0.25.0 | 13/04/2018 | DY | typo with infoWrite commands and workstation number. Implements BBC_GETWORKSTATIONNUM - some things still use it
2.0.26.0 | 20/04/2018 | DY | Mutex lock-up fix when trying to remove a device
2.0.27.0 | 24/04/2018 | DY | Removes extended range support
2.0.28.0 | 24/04/2018 | DY | Historic use of the top bit of the device number to indicate 32 bit messaging (that infodriver32/grd32 doesn't use) was confusing this app. Now masks appropriately
Build: master 3586 0d983c63 Atos © 2018