bncs_csi

BNCS Control System Interface: bncs_csi

Overview

An overview of what CSI does and how it does it can be found here.

Description

bncs_csi 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.

It is intended for systems with a V4.x environment only.

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 with redundancy mastering
  • Configurable external quality of service settings file
  • extended device/index ranges to the maximum extent of the IPC messages
  • direct driver messaging
  • Driver status infodriver
  • enhanced IPC for access to 32 bit device/index/database

Notable ommissions:

  • Workstation uniqueness checking (included at transport level in xDS)
  • Workstation status infodriver
  • 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
  • time server/client (use Windows NTP)

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.

Transport

bncs_csi doesn't send any network messages itself. It relies on an external DLL to do it. It's possible therefore to run CSI on different transports.

At time of writing two exist (with more possible)

Implementation | Documentation | Notes
DDS | bncs_csi_dds | implementation of OMG standard for Data Distribution Service by PrismTech
xDS | bncs_csi_xds | plain-old-sockets/multicast

Both are implemented in a DLL called "netlegacy.dll" and so which transport is used is determined by which DLL bncs_csi finds in the path.

Configuration/Command Line

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

Option | Value
/domain=x | For DDS, this has been superseded by reading the value directly out of the ospl.xml file so that you do not need to specify it here For xDS it sets the IP port number offset.
/devicestatus=995 | Internal device status infodriver id

Environment

Normal V4.x environment settings:

Variable | Value
CC_ROOT | path to root of one or more BNCS systems
CC_SYSTEM | folder of current BNCS system
CC_WORKSTATION | workstation number

Dependencies

The following files are required in windows\lib

File | Notes
netlegacy.dll | Wrapper for network access
qt5core.dll | Qt
qt5gui.dll | Qt
qt5network.dll | Qt
qt5widgets.dll | Qt
qt5xml.dll | Qt
qt5xmlpatterns.dll | Qt
qwindows.dll | Qt (in subfolder platforms\windows)

Maximum indexes using original inter-process communications (IPC)

You need to be concentrating for this bit. These are IPC limits - the bit that transfers messages about between applications on a workstation. These are not related to network, client or driver limits, just the values that can be transferred between applications.

Internally, and on the wire, bncs_csi uses 32 bit values for nearly everything - so number of devices, maximum number of indexes (slots/destinations), number of destinations etc.

So if you can get the value to bncs_csi, it can send it.

However, backwards compatibility means that existing drivers can only access to the maximums set out below.

  • Original IPC limits are the messages that old versions of CSI will understand
  • Extended IPC limts are only understood by bncs_csi and applications that have been adapted to use it

Original IPC limits:

32767 devices (1 to 32767)

This is limited by some messages that use 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

Database names

Stuck (and actively cropped at version 2.1.11) at 255 characters because of legacy buffer size in the API

Extended IPC limits

To use these new limits, different IPC messages need to be used. These are set out in the document "csi_ipc_update" included with the interfacing documentation.

For best compatibility of new and old, new drivers/clients should use the old IPC until the numbers get "too large", then use the new messages.

Devices: 32 bit value (2^32)-1 = 4294967295

bncs_csi and IPC implements 32 bits, but other factors limit the effective range to 31 bits (historic signed/unsigned values)

Databases: 32 bit value (2^32)-1 = 4294967295

bncs_csi and IPC implements 32 bits, but other factors limit the effective range to 31 bits (historic signed/unsigned values)

Indexes (slots/dests): 32 bit value (2^32)-1 = 4294967295

bncs_csi and IPC implements 32 bits, but other factors limit the effective range to 31 bits (historic signed/unsigned values)

sources: 32 bit signed value (2^31)-1 = +/- ‭2,147,483,647

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 (original IPC)

BBC_REGDEVICEID32_32

Driver registration (extended IPC)

BBC_GETMAXDATABASES

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

BBC_GETMAXSTRINGSIZE

Return the maximum size of string

BBC_GETMAXDESTS BBC_GETMAXSOURCES BBC_GETMAXSOURCENAMES BBC_GETMAXDESTNAMES BBC_GETMAXWORKSTATIONS

Return max capacity of CSI

BBC_CLEARDATABASECACHE

Clear loaded/cached databases

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 (original IPC)

BBC_CACHETEST_32

Cache functions (extended IPC)

BBC_REGCLIENT32, BBC_REGCLIENT

Handled the same to register a client

BBC_REGDEVICE, BBC_UNREGDEVICE, BBC_UNREGDEVICERANGE

"Revertive" registration functions (original IPC)

BBC_REGDEVICE_32, BBC_UNREGDEVICERANGE_32

"Revertive" registration functions (extended IPC)

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", "GQ" are supported.

Note: Query commands IQ, RQ and GQ are handled no differently from poll commands IP, RP and GP.

BBC_GETDBASENAME, BBC_GETDBASEINDEX, BBC_GETDBASEINDEXEXT

Database functions (original IPC)

BBC_GETDBASENAME_32, BBC_DATABASECHANGE_32, BBC_GETDBASEINDEXEXT_32

Database functions (extended IPC)

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, BBC_SETREDUNDANCYMASTER

Redundancy messages (original IPC)

BBC_SETREDUNDANCYMASTER_32

Redundancy messages (extended IPC)

Device Status Infodriver

Regular redundancy messages enable us to monitor availability and location of BNCS drivers.

bncs_csi creates an "internal infodriver" (if configured on the command line) where it returns data on location of BNCS devices.

Each slot corresponds to a BNCS device number, and the data contained in that slot is the workstation hosting a driver for that device.

For example:

001T,002R,003B

in slot 4 would indicate that BNCS driver id 4 is running TX on workstation 1, RxOnly on workstation 2, and RxOnly-broken (not able to go TxRx) on workstation 3.

It would be an error if:

  • there is more than one device TxRx
  • there is no device TxRx

Logging

bncs_csi itself doesn't generate any logs.

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 (and unnecessary) 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
2.0.29.0 | 15/05/2018 | DY | Implementation of RD command to make FABIAN/slink work
2.0.30.0 | 18/05/2018 | DY | Long-standing inexplicable hole in cache-get function - only returns the database name for the given router or GPI value not the numeric index. Now uses (previously unused) return value to give that value
2.0.31.0 | 18/05/2018 | DY | Device Profile now purely on existence of sizes not existence of database
2.0.32.0 | 18/05/2018 | DY | Knotty thready issue not updating UI for Txrx states (UI interaction from non-UI thread), and thready issues around use of m_cache
2.0.33.0 | 29/05/2018 | DY | Formatting error on debug string - debug message appears about missing parameter for a message that doesn't need one - now corrected.
2.0.34.0 | 31/05/2018 | DY | Messaging window was unnecessarily muting IPC traffic during closedown meaning that any closedown messages sent as drivers closed weren't able to hit the network. Now corrected.
2.0.35.0 | 04/07/2018 | DY | My long-term test interrupted by a test application crash which I couldn't re-run because CSI won't allow reconnecting of crashed driver. It will now (following same rules as CSI32 for checking Window handle)
2.0.36.0 | 09/08/2018 | DY | Deregister all wasn't. Is now.
2.0.37.0 | 17/09/2018 | DY | API call BBC_CLEARDATABASECACHE implemented
2.0.38.0 | 25/09/2018 | DY | Implements BBC_GETMAXSTRINGSIZE
2.0.39.0 | 25/09/2018 | DY | Reconsituting RL,GL and IL commands was faulty - had all 5 parameters in the call, but only 4 placeholders for the values. Upshot, workstation parameter was missed off
2.0.40.0 | 23/10/2018 | DY | Removes DDS version information from about box - this can only be best guess since it is not available programatically from the DDS implementation itself
2.0.41.0 | 05/11/2018 | DY | Reminds slave drivers that try and assert their own TxRx state what the state of the master is (fix to match CSI32 and a flaw with infodriver32 - see BST-404)
2.0.42.0 | 15/11/2018 | DY | Adds handling of BBC_GETHWNDCSI which ordinarily this app won't be able to hear, but may get forwarded by the csi32fix.exe application
2.0.43.0 | 29/11/2018 | DY | Adds implementation of device message / net status commands/response to match csi32 (required for slinky)
2.0.44.0 | 30/11/2018 | DY | Adds new "netStatus" DDS channels for the new required data type
2.0.45.0 | 05/02/2019 | DY | CORE-139 Uses correct casts for "unusual" characters that the default fromUTF8 doesn't convert properly - needs fromLatin1
2.0.46.0 | 06/02/2019 | DY | CORE-143 Adds workstation override capability (primarily for slink). IW, IL, RC, RL, GS, GL commands
2.0.47.0 | 18/02/2019 | DY | CORE-151 DDS config and log menu items
2.0.48.0 | 26/03/2019 | DY | Adds device status (internal device infodriver) to match CSI32 functionality. Changes go RxOnly to not just send an NC but also set the rxonly flag. Functionally it's the same, but it's not actully closing, it still indicates it's RXOnly
2.0.49.0 | 01/04/2019 | DY | Much massaged version of 2.0.48, changed on-the-wire redundancy constants to split state and command elements (e.g. TX can be combined with OBJECTION)
2.1.0.0 | 02/04/2019 | DY | Changed QoS to read from separate sections for each message type so that QoS can be honed for each one. NOTE: Not directly compatible with earlier QoS.
2.1.1.0 | 15/05/2019 | DY | Implementation of BBC_GETMAXWORKSTATIONS
2.1.2.0 | 07/06/2019 | DY | Rebuilt against changed netlegacy.dll (naming changes, additional "originating workstation" field)
2.1.3.0 | 07/06/2019 | DY | Fix to targeting of revertives
x.x.x.x | 05/09/2019 | DY | Minor docs update to include netlegacy as a dependency
2.1.4.0 | 24/09/2019 | DY | CORE-186 Startup-crash - fix to not use message window before it's created
2.1.5.0 | 31/10/2019 | DY | CORE-190 Reads domain number from ospl.xml rather than requiring a command line override. New dependency: Qt5XmlPatterns.dll
2.1.6.0 | 13/11/2019 | DY | Ensures that attempts to open the config files throw sensible error boxes if they fail
2.1.7.0 | 13/11/2019 | DY | BST-664 More discerning when detecting loss of client (to allow for IPC breakdown) and also adds checking of driver messages as per CSI32. Also a mutex fix to removing clients as I happened to spot it.
2.1.8.0 | 19/11/2019 | DY | Changes having reviewed 2.1.7
2.1.9.0 | 20/11/2019 | DY | BST-664 - full implementation to match csi32 that kills off an entire redundancy group if it's discovered that one part of it has died
2.1.10.0 | 27/11/2019 | DY | BST-667 - reworks creation of DDS readers/writers for optimum performance
2.1.11.0 | 10/12/2019 | DY | BST-696/BST-697 Database call was allowing copying of names greater than the guaranteed size of the buffer that will receive it
2.1.12.0 | 07/02/2020 | DY | BST-664 Various SendMessage calls were not sending the right length data - some one byte short, some the overall size of the buffer
2.1.13.0 | 11/02/2020 | DY | Tiny scope change to variable outside of mutext that protects it
2.1.14.0 | 12/02/2020 | DY | BST-664 - take the value, then remove (not the other way around)
2.1.15.0 | 12/02/2020 | DY | BST-664 - going external with IPC with a mutex locked is a complete no-no. Turned into a yes-yes.
2.1.16.0 | 28/02/2020 | DY | Massaging of OSPL string to allow extration of domain id from the XML
2.1.17.0 | 27/03/2020 | DY | Pragmatic change for bugfix for bncslib implementation which mistakenly sends WM_DESTROY message to the messaging window. This accidentally resets the HWND in handleshare.dll.
2.2.0.0 | 02/07/2020 | DY | Renames to indicate DDS not the only implementation (CORE-217)
2.2.1.0 | 17/08/2020 | DY | CORE-50 Removes blank toolbar
2.2.2.0 | 15/10/2020 | DY | Largely irrelevant handle-close for the main function
2.3.0.0 | 20/10/2020 | DY | Full range of the transport brought out in new IPC calls.
2.3.1.0 | 20/10/2020 | DY | Fixes to 2.3.0.0
2.3.2.0 | 22/10/2020 | DY | Adds 32 bit redundancy mastering IPC message
2.3.3.0 | 07/12/2020 | DY | Signed->unsigned variable changes with update to database classes
2.3.4.0 | 13/01/2021 | DY | Reinstates code to set the redundancy state on the UI from the incoming network message. This was erroneously removed with the redundancy mastering code
2.3.5.0 | 15/01/2021 | DY | CORE-300 Slightly scrappy handling of redundancy check code when sending driver messages?
2.3.6.0 | 08/02/2021 | DY | CORE-324 File->Close menu wasn't working. It is now.
2.3.7.0 | 17/02/2021 | DY | CORE-331 Adds registration count to the bncs_csi UI
2.3.8.0 | 21/02/2021 | DY | CORE-236 Pragmatic restriction to make number of workstations in DDS the same as xDS (65535). Checks the workstation number on start-up.
2.3.9.0 | 21/02/2021 | DY | BST-952 fixes/optimisations as a result of csi32 bug. Headline is edge-case if you supply a null value for HWND when de-registering a driver.
2.3.10.0 | 18/02/2021 | DY | CORE-318 Docs-only update
Build: bncs_4.7.5 5800 a1b48197a Atos|Syntel © 2021


bncs_csi_dds

BNCS Control System Interface: bncs_csi - DDS Transport

Environment

DDS requires the following environment variables:

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.
ADLINK_LICENSE | <your system root>\config\dds\license.lic This value does not seem to require the file: prefix of the previous entry

These are set by workstation manager on the fly if this application is run from within that so you don't need these configured in your environment.

Note: If you do configure them in your environment you risk using the configuration/qos files from one system on a different system - so really don't set them unless you really have to.

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
dds_security_core.dll | DDS

Logging

DDS creates two logs in the working directory (typically windows\bin):

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

Upgrading to new bncs_csi releases with DDS transport

DDS

Use of DDS means we have to play by certain rules. When a DDS participant tries to join 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

DDS 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...

QoS sections

From bncs_csi version 2.1.0.0, quality of service has been split into separate sections for the different message types.

This view of collapsed XML gives you an outline.

Previously, only the "default" section was used. This version splits into individually configurable sections. The latency budget for example for commands may be very strict, less so for "revertives" and can be downright tardy when it comes to redundancy messages.

Splitting gives opportunity to hone for each message type. Section names are as defined below:

Section Name | Use
default | The original section name, no longer required
bncs_commands | Commands such as InfoWrite, RouterPoll, routerModify, routerDatabase
bncs_revertives | Responses such as InfoRevertive
bncs_redundancy | The 'N' messages that control redundancy and give driver status
bncs_netstatus | The direct-driver-messaging

Note, both profile name and individual section names (e.g. datareader_qos) need to be the same

Build: bncs_4.7.5 5800 a1b48197a Atos|Syntel © 2021


bncs_csi_xds

BNCS Control System Interface: bncs_csi - xDS transport

Overview

xDS is a "plain sockets" custom implementation of a network protocol to carry BNCS traffic across a LAN.

Similar in concept to the NetBIOS protocol it replaces, but in a modern implementation, with modern network protocol and several advantages:

  • UDP unicast/multicast delivery
  • optional encryption
  • automatic "session-based" poll responses
  • greater string size

Environment

Same as bncs_csi

Dependencies

Same as bncs_csi with addition of (in windows\lib):

File | Notes
libeay.dll | OpenSSL

Logging

None

Configuration

Configuration is contained within the file: config\xds.ini

Documentation

This is a terse overview. This module/transport is documented separately.

Build: bncs_4.7.5 5800 a1b48197a Atos|Syntel © 2021


overview

CSI Overview

Description

This is a general overview of BNCS CSI application. It is applicable to any version.

Fundamentally, BNCS systems are made up of a collection of executables which:

  • interface to equipment
  • provides a user interface

The purpose of CSI is:

  • provide a single node to the network (rather than one node per application) and so aggregate/split messages appropriately, to make best use of machine and network resources
  • provide and maintain simple "database" services (key-value pairs)
  • negotiate and maintain driver redundancy state
  • provide status to the network
  • provide status information to CSI's clients/drivers

So CSI - the Control System Interface sits between an internal API and the network:

CSI provides an interface for both client and driver in the same application - though these are two independent messaging channels.

BNCS Messaging

BNCS messages are simple. Devices are addressed using a simple numeric ID. These devices can have a number of slots or destinations to which you either write a string or numeric value.

That's really all there is too it. All manner of devices have been controlled using this simple mechanism, and entire broadcast systems implemented using it.

Internal API

This is based on a (historic) SendMessage mechanism that can be used to send simple, short numeric and/or text messages between separate executables:

In it's simplest form it sends a message and just two numbers, but can also be used to send a number and a data buffer. Typically the buffer is a string, but there are some simple data structures that get used.

What gets sent, what the values mean is entirely dependent on the message - but they all get funnelled via this mechanism.

All the values, what they mean are all documented separately.

Network

So long as CSI presents a consistent API to the applications, it doesn't matter what the network transport is.

The CSI function has been implemented to use

  • NetBIOS over NetBEUI
  • NetBIOS over IP (UDP)
  • DDS (multicast)
  • xDS (our own multicast implementation)

Indeed the same API has been used to provide a "CSI-like" application that works TCP/IP

Other services

CSI also provides simple "database" services - which really means multiple arrays of key-value pairs

The Messages Conveyed

This is a list of the common messages conveyed on a BNCS network. Early CSIs will carry other messages and their free-form nature means this list can't be comprehensive.

These are the core messages that make a BNCS system work. You'll see these displayed in their raw form on the network monitoring tools (typically known as "CapLog") and are each separate messages on the internal API. We'll investigate one of these later.

Message | Known As | Notes
Info Write | IW | Write a value to a slot
Info Poll | IP | Request dump of current infodriver values
Info Query | IQ | Request dump of current infodriver values^1
Info Lock | IL | Lock (set read-only) a slot
Info Revertive | IR | Poll reply or change of state
Router Crosspoint | RC | Make a route between source and destination
Router Poll | RP | Request dump of current infodriver values
Router Query | RQ | Request dump of current infodriver values^1
Router Lock | RL | Lock (set read-only) a destination
Router Revertive | RR | Poll reply or change of state
GPI Switch | GS | Switch a GPI
GPI Poll | GP | Request dump of current infodriver values
GPI Query | GQ | Request dump of current infodriver values^1
GPI Lock | GL | Lock (set read-only) a destination
GPI Revertive | GR | Poll reply or change of state
Router Modify | RM | Change a "database" value
Router Database | RD | Change a "database" value ^2
NetStatus | NS | Directed client->driver messaging
Network Active | NA | Redundancy message
Network Objection | NO | Redundancy message
Network Inquiry | NI | Redundancy message
Network Broken | NB | Redundancy message
Network Slave | NV | Redundancy message

^1 Query and Poll are requesting the same data, but each specifies how the data is to be returned. Different CSIs handle these in different ways.
^2 The peer to peer nature of database change notifications makes bridging networks hazardous - so this is a "don't forward" variation on the "Router Modify" message to allow for this

Some others you might come across not supported in later CSIs

Message | Notes
Info File | Write a value to remote file
Info Hardcopy | Write a value to a remote printer
Router File | Used to indicate to a driver it should reload it's configuration
FABIAN redundancy | Many 'F' messages that provide a similar function to the "Network" messages listed above

Internal API - Example

As noted you can only send a specific message, two numeric values, or one numeric value and a string.

The general function call is:
SendMessage( destination, messageId, numericValue, numericValue )
or with the variation:
SendMessage( destination, messageId, numericValue, pointerToBuffer )

The "InfoWrite" command

This is a command from a client application/executable via CSI to a driver.

The general format of the command is:

IW <deviceId> '<string>' <slot> <workstation>

for example

IW 123 'hello' 456 789

Which means: On device 123, write the string 'hello' to slot 456, and I'm workstation 789.

On the internal API this command is sent as a string - so literally the text (exactly as shown above):

IW 123 'hello' 456 789

This is then conveyed using whatever mechanism your version of CSI uses across the network to another CSI which passes it to a driver application of deviceId 123

It's then presented as the same string to that driver. Some CSIs send the string as-is to the network - literally the string as shown. Other CSIs split into fields, send and reconstitute the string at the driver.

The sending API itself is defined like this:

This defines a generic "send an infodriver command" message and tells you what to do with the two numeric parameters.

At the driver

The message that CSI receives from the network and passes to the driver is sent using this command:

This again is a generic message to pass "a command" to the driver - but in our case the IW command.

History

CSI itself goes back a long way!

Version 1.00 -  16/12/93    - Development commenced

It's been through many variants:

Version | Architecture | Networking | Notes
csi | 16 bit | V1 over NetBIOS | first version
v2csi | 16 bit | V2 over NetBIOS | enhanced network messaging
v3csi | 32 bit | V2 over NetBIOS | 32 bit version of v2csi
v4csi | 32 bit | V2 over NetBIOS | different environment and UI
csi32 | 32 bit | V2 over NetBIOS | unified & enhanced version of v3csi and v4csi
bncs_csi | 32 bit | DDS / xDS | Ground-up rebuild of CSI

Transports Compared

As I note above, so long as CSI implements the expected API, the application doesn't really care how the message gets there.

V2 BNCS networking over NetBIOS

"V2" refers to the generation of BNCS networking, not a specific CSI version

Points to note:

  • NetBIOS packet delivery to named network endpoints
  • Uses network broadcasts (dest = 192.168.1.255)

  • Command sent as space-delimited string

xDS Messaging

Points to note:

  • Multicast delivery (dest = 239.255.0.44)

  • Command sent as binary data

Build: bncs_4.7.5 5800 a1b48197a Atos|Syntel © 2021