Latest revision as of 12:02, 28 March 2017

[edit] Railbus Protocol (standard ASCII format)

The Railbus Protocol is designed to be as flexible as possible while being as easy as possible.

All data is transmitted on the RS485 with a baudrate of 9600:8N1 as printable ASCII characters. Any data is converted into the corresponding hexadecimal notation.
For convenient manual interaction Railbus devices append CRNL to responses.
This behavior can be controled via the system registers starting at 250 (0xFA).

[edit] Packet Layout

Every packet has a fixed length and is created as defined here:

[edit] MW - Magic word

The magic word is prepended to every packet and always consists of the two characters 'R' and 'P'. These characters never occour on the bus under normal conditions.

[edit] ADDR - Modul address as HEX

Each modul on the bus has a address. In its delivery-state, a modules address is set to 0. On modules equipped with a BCD-Display, the modules address is shown there. The modul address is one byte long and is transmitted as two characters.

Example: "0A" for the module address 10(decimal), the Modules BCD-Display will show "0A"

[edit] CM - command

The command consists of one byte, either an 'R', 'W', 'S', 'K', 'I' or 'N'. The value is not converted to hexadecimal notation. These command characters are not valid hexadecimal digits and therefore can not show up in the rest of the packet.

The different characters define the type of the packet, as shown in the following table:

[edit] SADR - Sub address or register address

The sub-address field selects the internal register choosed to be read or written. The sub-addresses 0 to 249 are interpreted device specific.Every module type has its own set of supported sub-addresses.

Registers 250 to 255 are "special" sub addresses for common issues. Not all registers are used on every device. Refer to the devices datasheet.
The sub-address 255(0xFF) is used for identifying a device (read command) and setting the module address (write command).
The sub-address 254(0xFE) is used for communication settings like CRNL append.
The sub-address 253(0xFD) is used to set the baudrate the device uses.
The sub-address 250(0xFA) is used to put the device in delivery state. All properties except the railbus settings are reset.

Write requests to read only registers are NACKed by a special nACK with status code "Forbidden", so are read requests to write only registers. Not implemented addresses are responded by an Not Acknowledge.

[edit] SADR 255 (0xFF) - Modul identification

Layout :

Reading the register will transmit the Devices ID and its current address. On writing the address the 24 higher bits are ignored and only the address will be set to a new value. The corresponding ACK will use the old address but new commands are only accepted on the new one.

The IDs can be like "R66" for the Din Rail Relais 6I6S. Refer to the devices datasheet for specific information.

[edit] SADR 254 (0xFE) - Communication Settings

Layout:

This register is set to zero during device reset or power on.

If bit noCRNL is set the device suppresses appending of CRNL to packets.
If bit noACKs is set the device suppresses responses to succesful write commands.

[edit] SADR 253 (0xFD) - Baud Rate

This register is set to the default baudrate of 9600 (0x2580) on power on or device reset.
Setting the baudrate to zero forces use of the default railbus baudrate of 9600 (0x2580).
The success response to a change in baudrate is transmitted using the new value.
Most of our devices support the higher speed baudrate of 57600 (0xE100), some even higher ones. Consult the devices datasheet for specific information.
Trying to set an unsupported baudrate is NACKed with the special nACK 0x09 (invalid Data).

[edit] SADR 250 (0xFA) - Factory Reset

Write the value 0x1F2E3D4C to this register to put the device back into delivery state.
All properties except the railbus settings (SADR 250-255) are reset.

[edit] DATA - the register data and (N)ACK types

In the 'K', 'I' and 'W' modes this field consists of 32bit hexadecimal notated data representing the register content and is transmitted in eight characters. In the 'n' Mode this field contains information about the type or reason for the (N)ACK.

[edit] CHK - Checksum

The checksum consists of one byte of data, transmitted as two hexadecimal notated characters. If the MSB is set, the checksumming is enabled, using CRC7 on all of the preceeding data. If the MSB isnt set, checksum is ignored.

[edit] Usage

A write should be repeated as long as no corresponding (N)ACK is received. Devices should execute each Write command only once but deliver an Special ACK for each received copy. The special sync command counts as a write command and as such breaks this loop. If currently a command is processed and therefore the queue couldn't be cleared, the Sync is NACKed.

Only one write can be executed at once. Reads can be executed any time.

[edit] Special ACKs 'n'

• DATA: 0x01 - ACK Received. The command was received and will be executed.
• DATA: 0x02 - ACK Retransmission. The command was received is currently executed.
• DATA: 0x03 - ACK Done before. The command was already received and finished.
• DATA: 0x06 - NACK Unknown. Unknown Register.
• DATA: 0x07 - NACK Forbidden. Read on Writeonly Register or Write on Readonly one.
• DATA: 0x08 - NACK Busy. Write received but already executing command.
• DATA: 0x09 - NACK Invalid. Command could not be executed. Invalid Data.
• DATA: 0x0A - NACK Error. Command aborted.
• DATA: 0x0B - NACK Abort before. Command was already aborted in the past.
• DATA: 0x10 - ACK Synced. The Sync was succesfully completed.

[edit] Railbus Protocol binary extension

the binary extension to the railbus protocol is for automated transmissions of data only.

[edit] Packet Layout

Packets using the binary extension do have a variable length and have the following layout:

[edit] MW, ADDR

the Magic Word and the destination address are encoded like in the standard ASCII railbus protocol.

[edit] CM - Command

The command for the binary extension always has the highest bit set to flag the variable packet length.

The defined commands are implementation specific. The command is transmitted as one character.

[edit] LENGTH - packet length

The Length field specifies the number of character transmitted for the complete packet. It is a 16bit integer transmitted in 4 hex-coded characters.

[edit] SRCA - source address

The source address is defined as the address of the sender. Like the ADDR-field is is transmitted in two characters.

[edit] SE - sequence number

An ongoing sequence number. Every packet in an ongoing stream has this field incremented to provide a unique packet identification. The number of the first packet in a stream should be used on a random base.

The sequence number is represented as a 8bit integer, transmitted unencoded in one character.

[edit] DATA - variable length data

the rest of the packet consists of unencoded databytes.

[edit] CHK - variable length data

the checksum is encoded and calculated as in the standard ASCII railbus protocol.

[edit] Examples

[edit] Example 1: Request for current Status on a DIN Rail Relais 6I6S

For reading the current status on a Relais 6I6S, the first line of the following listing should be send; the board will answer with the second line.

 RPFFR0000
 RPFFK000015002A00

1. Every packet starts with the magic characters R and P.
2. The next two characters contain the hexadecimal encoded address of the board. In this case, the board listens at the address 0xFF (or 255 in decimal notation).

Note: The module address 255 is the default address after factory reset!

1. Following the address, the command is transmitted
   • In case of the Read Request, an R is transmitted
   • In case of the Read Acknowledge - the answer of the board - an K is transmitted
2. Next the SADR is put on the line. In this example the register 0 is accessed.
3. Only in the Read Acknowledge, 8 characters forming 4 Bytes of data are transmitted. In this case the state of the inputs and outputs is transmitted.
   • In the second Byte of the data, representing bit 23-16 of the register, the state of the inputs is shown. Here DIGIN1, DIGIN3 and DIGIN5 have a voltage detected.
   • In the forth Byte, representing bit 7-0 of the register, the state of the outputs is shown. Here REL2, REL4 and REL6 are on.
4. The last two characters contain the checksum. In this case, the dummy-checksum '00' is used. This means no validity checking is performed.

[edit] Example 2: Write to DIN Rail Relais 6I6S at module address 0x93, set Relays to 0x10 (only relais #4 on, all other are off)

 RP93W000000001000
 RP93I000000001000

1. The SADR 0 is accessed.
2. 8 characters forming 4 Bytes of data are transmitted.
3. The module answers with a Write-Acknowledge 'I'

[edit] Example 3: same as Example 2 but store the value to internal EEPROM too

 RP93W010000001000
 RP93I010000001000

The SADR 1 is accessed. The content is written into internal EEPROM too and then restored after reset or power-loss! See Ralais 6I6S documentation for details!

[edit] Example 4: Set the baudrate to 57600

 RP93WFD0000E10000

The SADR 253 is accessed and the value for the baudrate set to 0xE100 which equals 57600 b/s.
The ACK to this command is issued using the new setting and might not be visible in the terminal application.

If the baudrate is not supported on this device it answers with the special nACK 0x09 (Data invalid):

 RP93nFD0000000900

[edit] Adding a valid checksum

The checksum is calculated as CRC7, like used in communication in MMC or SD-Cards. The theory is described in Wikipedia:Cyclic redundancy check. This CRC7 is or'ed with a 0x80, to have the highest bit set and enable the checksum-checking.

To calculate the checksum, the function crc7_calc in the following code can be used:

const unsigned char crc7_table[16] = {
	0x00, 0x12, 0x24, 0x36, 0x48, 0x5a, 0x6c, 0x7e,
	0x90, 0x82, 0xb4, 0xa6, 0xd8, 0xca, 0xfc, 0xee
};

static unsigned char crc7_next(unsigned char crc, unsigned char dat)
{
	crc ^= dat;
	crc = ((crc << 4) & 0xff) ^ crc7_table[crc >> 4];
	crc = ((crc << 4) & 0xff) ^ crc7_table[crc >> 4];
	return crc;
}

unsigned char crc7_calc(const unsigned char *dat, unsigned short len)
{
	unsigned char crc = 0;

	if (len) do {
		crc = crc7_next(crc, *dat++);
	} while (--len);

	return (crc >> 1)|(1<<7);
}

[edit] Changelog

[edit] v2.2

• specified baudRate settings

[edit] v2.1

• Reserved Register 0xFE for Communication Settings

[edit] v2.0

• added Packet Type 'S' (Sync)
• added Packet Type 'n' (N)ACK with reason
• Section 'Usage'

[edit] v1.0

• initial release