MSCB Protocol

General command structure
Addressing
Node variables
Configuration Parameters
Commands
Timeouts
Auto repeat mode

Back

Protocol Introduction

The software protocol, which runs on the node microcontroller on one side and at the master PC on the other side is optimized for typical applications in nuclear and particle physics experiments. It does not conatin all the features from traditional field buses, but is therefore much more simple. The protocol implements a master-slave scheme, where the PC is the master and the nodes connected to the hardware are the slaves. If several masters are present on the bus (like a backup PC for redundancy), they have to share the bus via a token ring scheme.

General command structure

The protocol is byte-oriented and uses bit 9 from RS-232 (which is sometimes used as a parity bit) for addressing purposes. The first byte contains the command, which consists of a 5-bit command and a 3-bit parameter length. The parameter length specifies the number of bytes which follow the command. Zero means no parameters, a binary 110 means 6 bytes, and a binary 111 means that the following byte specifies the number of bytes (0 - 127) or the following two bytes specify the number of bytes (MSB with high bit set, LSB). This feature can be used to pass commands with variable parameter length. The command and the parameters are followed by a 8-bit CRC code evaluated over all command and parameter bytes, which uses the CCITT-8 polynomial

X^8 + X^5 + X^4 + 1
Following figure explains this scheme:

Command bitsParametersDescription
xxxxx 000[CRC] command only
xxxxx 001[byte1] [CRC] Single byte parameter
xxxxx 010[byte1] [byte2] [CRC] Two parameter bytes
...
xxxxx 110[byte1] [byte2] ... [byte6] [CRC]Six parameter bytes
xxxxx 111[N] [byte1] [byte2] ... [byteN] [CRC]N parameter bytes (0 - 127)
xxxxx 111[0x80 | MSB N] [LSB N] [byte1] [byte2] ... [byteN] [CRC]N parameter bytes (128-32767)

If two or four parameter bytes compose a word or double word, they are passed LSB fist, then MSB.

Addressing

Because all nodes are connected in parallel to the bus, an addressing scheme must be used to talk to individual nodes. Three address modes are available, individual node addressing, group addressing and broadcast addressing . For this purpose, each node has an unique node address and a group address which are both two bytes long. For small networks with less than 256 nodes, the addressing is done with a single byte. The MSB address byte of all nodes must then be zero. For larger networks, a 16-bit address can be used, allowing for up to 65536 nodes. The address of a node is programmed on its initial configuration, but can be changed later via the command CMD_SET_ADDR. By default, a new (unconfigured) node has address 0xFFFF. When the network is configured, one uncofigured node at a time can be added to the network, addressed with 0xFFFF, and then configured for a specific node address via CMD_SET_ADDR.

Following commands are used for addressing:

Command bitsParametersNameDescription
00001 001 (0x09)[address byte] [CRC]CMD_ADDR_NODE8 8-bit individual node addressing (short address)
00001 010 (0x0A)[address byte MSB] [address byte LSB] [CRC]CMD_ADDR_NODE16 16-bit individual node addressing (long address, large networks)
00010 001 (0x11)[address byte] [CRC]CMD_ADDR_GRP8 8-bit group addressing (short address)
00010 010 (0x12)[address byte MSB] [address byte LSB] [CRC]CMD_ADDR_GRP16 16-bit group addressing (long address, large networks)
00010 000 (0x10)[CRC]CMD_ADDR_BCBroadcast (all nodes are addressed)
00011 001 (0x19)[address byte] [CRC]CMD_PING8 Ping with 8-bit node address
00011 010 (0x1A)[address byte MSB] [address byte LSB] [CRC]CMD_PING16 Ping with 16-bit node address

Group addressing can be used to send commands to a whole group of nodes. Of course this works only for write commands without acknowledge. One example would be that all high voltage channels in an experiment belong to a single group. By addressing this group, all channels can be turned off with a single write command.

After a node is addressed in individual mode, all further communication is done with this node, until another address command is issued.

The ping command can be used to check if a node is alive. The node is requested to return an acknowledge command (see below) within 100us.

All address commands have bit 9 set in all their bytes, which is used by the microcontrollers to distinguish address commands from other communications. If for example a large buffer of data is transferred to a node, other nodes could interprete some of the data bytes as address commands and be falsely addressed. To avoid this, all commands other than the address commands have bit 9 not set.

Node variables

Each node may contain up to 256 node variables which can be used to communicate with the node. Each node variable is stored locally on the node in RAM and can be copied to EEPROM with the CMD_FLASH command. Variables are read with the CMD_READ or CMD_READ_RANGE commands and can be written with the CMD_WRITE_NA and CMD_WRITE_ACK commands. Upon reading or writing of variables, a user routines is triggered on the remote node which can communicate the variable contents to physical entities like ADC and DAC channels. This might not be necessary for some variables which can act like configuration parameters.

Variables can be 1 to 256 bytes long, depending on node memory. They contain a name, some flags and a physical unit like Volts, Ampere, etc. This way one can communicate with a node without a priori knowledge of its variables. This scheme is called "self-documenting network". The parameters of the node variables can be queried wit the CMD_GET_INFO command.

Variables are specified by their index ranging from 0 to 255.

Commands

Following table lists all commands which have to do with configuration issues:

Configuration oriented commands
Command bitsParametersNameDescription
00100 000 (0x20)[CRC]CMD_INITInitialize node (soft reset)
00101 000 (0x28)[CRC]CMD_GET_INFORequest general node info item, response (0x7F) see below
00101 001 (0x29)[index] [CRC]CMD_GET_INFORequest info for a specific variable. For the response (0x7F) see below
00110 110 (0x33)[mode]
[address MSB]
[address LSB]
[CRC]
CMD_SET_ADDR Overwrite address (goes into non-volatile EEPROM)
mode=1: Set node address
mode=2: Set only high byte of node address
mode=3: Set group address
00110 111 (0x37)[length]
[name] (1..16 bytes)
[CRC]
CMD_SET_NAME Overwrite node name
00111 001 (0x39)[index] [CRC]CMD_SET_BAUDSet baud rate (goes into non-volatile EEPROM)
1=9600,2=19200,3=28800,4=57600,5=115200,6=172800,7=345600
01000 001 (0x41)[1/0] [CRC]CMD_FREEZE Freeze command. When this command is broadcasted (after a group has been addressed), all group members are required to measure their values immediately and keep this value until read out. Broadcasting this command with "0" in the second byte finished the freeze mode. Using this command, one ensures that all values read out from the slaves are measured at the same time.
01001 001 (0x49)[1/0] [CRC]CMD_SYNC Sync command. When this command is broadcasted (after a group has been addressed), all group members are required to keep their demand value in an internal buffer and only propagate it to the hardware when the sync mode is turned off (With a "0" in the second byte). Using this command, one ensures that all values sent to the slaves are applied at the same time.
01001 110 (0x4E)[day] [month] [year]
[hour] [minute] [second] [CRC]
CMD_SET_TIME Sets the current date/time on any real time clock on the node. The values are BCD encoded, such as 0x12 means '12'. [year] goes from 00 to 99.
01010 000 (0x50)[CRC]CMD_UPGRADEEnter upload mode for upgrading firmware program
01011 xxx (0x58)[CRC]CMD_USERCall user function. This function is application specific and may contain 0-6 parameters which are passed to the user function on the remote slave node.
01100 001 (0x61)[byte] [CRC]CMD_ECHOThe echo function returns [byte] and can be used to test the quality of the communication.
01101 000 (0x68)[CRC]CMD_TOKENReserved for future use in multi-master environments
01110 000 (0x70)[CRC]CMD_GET_UPTIMEReturns the node uptime in seconds

Following table show data oriented commmands:

Data oriented commands
Command bitsParametersNameDescription
Write data without acknowledge
10000 xxx (0x80+x)[channel] [value byte(s)] [CRC]CMD_WRITE_NA Write data to channel. The value bytes can be 1 to 4 bytes long (MSB first), depending on the channel width. The length bits in the command (xxx) have to be set accordingly from 2=010b (channel plus 8-bit value) to 5=101b (channel plus 32-bit value)
Write data with acknowledge
10001 xxx (0x88+x)[channel] [value byte(s)] [CRC]CMD_WRITE_ACK Write data to channel with acknowledge. The value bytes can be 1 to 4 bytes long (MSB first), depending on the channel width. The length bits in the command (xxx) have to be set accordingly from 2=010b (channel plus 8-bit value) to 5=101b (channel plus 32-bit value)
Flash data to EEPROM
Since EEPROMS withstand only a limited number of reprogrammings, it is recommended to use the command CMD_FLASH not too often.
10011 000 (0x98)[CRC]CMD_FLASH Write current values and configuration parameter permanently to EEPROM with acknowledge. This command can be used to make values and parameters "permanent", so that they are reloaded after a node reboots or a power cycle.
Read data from slave node
10100 001 (0xA1)[channel] [CRC]CMD_READRead value from channel
10100 002 (0xA2)[channel1] [channel2] [CRC]CMD_READRead set of values from channel1 to channel2
Data range transfer
10101 111 (0xAF)[N]
[channel1][channel2]
[value byte][CRC]
CMD_WRITE_RANGEWrite set of values from channel1 to channel2, N=number of bytes (N < 127)
[0x80 | MSB N]
[LSB N]
[channel1][channel2]
[value byte][CRC]
CMD_WRITE_RANGEWrite set of values from channel1 to channel2, N=number of bytes (N > 127)
Memory block write
10110 111 (0xB7)[0x80 | MSB N]
[LSB N]
[subaddress]
[address MSB]
[address byte2]
[address byte3]
[address LSB]
[(N-5) bytes of data]
[CRC]
CMD_WRITE_MEMWrite directly to node memory. (N-5)=number of data bytes.
Subaddress: optional byte for slot addressing in crates
Memory addresses:
0x00000000 - 0x0FFFFFFF RAM (volatile memory)
0x10000000 - 0x1FFFFFFF NVRAM (non-volatile memory)
0x20000000 - 0x2FFFFFFF EEPROM/FLASH
0x30000000 - 0x3FFFFFFF CODE (program code, write access must be with continous data blocks)
10111 111 (0xBF)0x07
[MSB N]
[LSB N]
[subaddress]
[address MSB]
[address byte2]
[address byte3]
[address LSB]
[CRC]
CMD_READ_MEMRead directly from node memory. N=number of data bytes.
Subaddress: optional byte for slot addressing in crates
Memory addresses:
0x00000000 - 0x0FFFFFFF RAM (volatile memory)
0x10000000 - 0x1FFFFFFF NVRAM (non-volatile memory)
0x20000000 - 0x2FFFFFFF EEPROM/FLASH
0x30000000 - 0x3FFFFFFF CODE (program code)
Logging Buffer
11000 001 (0xC1)[cmd][CRC]CMD_LOGcmd=0: Returns logging buffer, cmd=1: Clears logging buffer

The acknowledge command is used in responses from slaves and differs depending on the command which caused the acknowledge. Following table lists possible commands causing an acknowledge and the information returned in the acknowledge

Acknowledge 01111 xxx (0x78-0x7F)
Origin commandAck. bitsParametersDescription
CMD_PING01111 000{No CRC!}Reply to ping command, showing that node is alive
CMD_GET_INFO
General node info
01111 111
0x20 Length of response (32 bytes) without this byte and CRC
[protocol version] Version of MSCB protocol. The most recent version is 5
[# channels] Number of channels supported by node for reading/writing
[node address MSB] Node address programmed on configuration
[node address LSB]
[group address MSB] Group address programmed on configuration
[group address LSB]
[Revision MSB] First two bytes of the GIT commit hash of the current firmware version
[Revision LSB]
[node name] 16 zero terminated ASCII bytes describing node name
[RTC data] Value of real time clock in six bytes as DD MM YY HH MM SS
[Buffer size MSB] Maximum buffer size for CMD_READ_MEM / CMD_WRITE_MEM
[Buffer size LSB]
[CRC] CRC code on the above bytes
CMD_GET_INFO
Variable info
01111 111
0xC Length of response (12 bytes)
[size] Variable width (1=8bit, 2=16bit, 3=24bit, 4=32bit)
[units] Physical units, see table below
[prefix] Prefix of physical units, see table below
[status] Channel status not yet defined
[flags] Variable flags. Combination of following bits:
1=MSCBF_FLOAT channel in floating point format
2=MSCBF_SIGNED channel is signed integer
4=MSCBF_DATALESS channel doesn't contain data
8=MSCBF_HIDDEN used for internal config parameters
16=MSCBF_REMIN get variable from remote node on subbus
32=MSCBF_REMOUT send variable to remote node on subbus
[name] 8 zero terminated ASCII bytes describing variable
[CRC] CRC code on the above bytes
CMD_WRITE_ACK01111 000[CRC]For write with acknowledge commands, the CRC code of the original command is returned. No new CRC code is added.
CMD_WRITE_RANGE01111 000[CRC]For write range commands, the CRC code of the original command is returned. No new CRC code is added.
CMD_FLASH01111 000[CRC]Confirm success of flash operation.
CMD_SET_TIME01111 000[CRC]Confirm success setting of date/time.
CMD_READ01111 001[byte 1][CRC]For read commands, the data is returned as 1-4 bytes depending on the channel (MSB first). A CRC code is added by the slave.
01111 010[byte1][byte2][CRC]
01111 011[byte1][byte2][byte3][CRC]
01111 100[byte1][byte2][byte3][byte4][CRC]
CMD_ECHO01111 001[byte] [CRC]Echos original byte.
CMD_GET_UPTIME01111 100[MSB][byte 2][byte 3][LSB][CRC]Returns uptime in seconds.
CMD_WRITE_MEM01111 000[CRC]CRC code of the data block written to memory.
CMD_READ_MEM01111 111[0x80 | MSB N][LSB N][N data bytes][CRC]Returned data. A CRC code is added by the slave spanning the data and the first three bytes.
CMD_LOG (cmd=0)01111 111[0x80 | MSB N][LSB N][N data bytes][CRC]Returned logging buffer data. A CRC code is added by the slave spanning the data and the first three bytes.
CMD_LOG (cmd=1)01111 000[CRC]Returned logging successfully cleared.

The physical units of all variables and their optional prefix are listed here:

CodePrefix
-12PRFX_PICO
-9PRFX_NANO
-6PRFX_MICRO
-3PRFX_MILLI
0PRFX_NONE
3PRFX_KILO
6PRFX_MEGA
9PRFX_GIGA
12PRFX_TERA

CodeUnit
SI base units
1UNIT_METER
2UNIT_GRAM
3UNIT_SECOND
4UNIT_MINUTE
5UNIT_HOUR
6UNIT_AMPERE
7UNIT_KELVIN
8UNIT_CELSIUS
9UNIT_FARENHEIT
SI derived units
20UNIT_HERTZ
21UNIT_PASCAL
22UNIT_BAR
23UNIT_WATT
24UNIT_VOLT
25UNIT_OHM
26UNIT_TESLA
27UNIT_LITERPERSEC
28UNIT_RPM
29UNIT_FARAD
Computer units
50UNIT_BOOLEAN
52UNIT_BYTE
53UNIT_WORD
54UNIT_DWORD
55UNIT_ASCII
56UNIT_STRING
57UNIT_BAUD
Others
90UNIT_PERCENT
91UNIT_PPM
92UNIT_COUNT
93UNIT_FACTOR

Following notes apply:

Timeouts

To avoid system crashes when one node fails, timeouts are used. Each node is required to respond after a limited time, otherwise a timeout occurs. Following timeouts are used:

CommandTimeout
Standard MSCB commands10 ms
Ping command (0x1A)400 us
Flash data to EEPROM (0x98) and Upgrade (0x50)3 s

If a timeout occurs, the master retries the command sereral times. If the node does not respond to all commands it is declared dead and excluded from further communication.

Auto repeat mode (not yet implemented!)

In typical experiments, it is sometimes necessary to read a large number of channels (>1000), like in a high voltage control. The normal protocol requires one address command plus one data request with reply. This requires typical 4+3+4 = 11 bytes (Address command, read command and 16-bit data response including CRC bytes). Given a data rate of 115200 baud and zero delay in the nodes, a single node readout takes about 0.1 ms. For 1000 channels, one would need 1 sec. To improve this performance, an auto repeat mode is available. In this mode, each node sends its data consecutively without addressing, thus improving the performance.

To initialize auto repeat mode, the nodes first have to be addressed in group mode or broadcast mode. Then, the initialize auto repeat command (0xCa) is issued by the master. This command switches all addressed nodes into auto repeat mode. On the next Read next node command issued by the master, the node with the first node address N from the initizlize command responds with its node LSB address followed by the data as shown below:

Command bitsParametersDescription
Auto repeat commands
11001 100 (0xCC)[first node address MSB] [first node address LSB]
[first channel] [last channel] [CRC]
Initialize auto repeat mode
11001 000 (0xC8){NO CRC!}Read next node
Auto repeat response
[LSB node address][value] [CRC]8-bit values single channel
[LSB node address][first channel value] ... [last channel value] [CRC]8-bit values multiple channels
[LSB node address][value MSB] [value LSB] [CRC]16-bit values single channel
[LSB node address][first channel value MSB] [first channel value LSB]
...
[last channel value MSB] [last channel value LSB] [CRC]
16-bit values multiple channels

On the next Read next node command, the node with address N+1 responds, then N+2, and so on. To assure that the right node responds with its data, each data transmission contains the LSB of that node's address which can be checked by the master. It is necessary that nodes participating in an auto repeat sequence have consecutive node addresses. It is the task of the master to count the Read next node commands until all addressed nodes are read out and then reissue another Initialize auto repeat mode command, or continue with a normal addressing cycle. Using the auto repeat mode, a node can be read out with 1+5 = 6 bytes (1 Read next node command, one LSB address, 2 data bytes, one CRC byte), thus reducing the readout time by a factor of two.


July 18th, 2001, S. Ritt