RoomBus

RoomBus is a CAN-FD based bus for room monitoring and control.

Key Features

CAN-FD based
Multi-master
Up to 125 devices per line

Motivation

RoomBus was developed as a platform for room control and monitoring applications.

Inspiration

RoomBus was partially inspired by KNX. However, RoomBus is not intended as a replacement for KNX.

Terminology

RoomBus	This whole project including the hardware and software layer.
Kernel	Part of the firmware that boots the system, handles communication and runs the application.
Application	The user application.
Node	One entity on the bus.
Frame	Unit of data on the data link layer.
Packet	Unit of data on the network layer.
Message	Unit of data on the application layer.

Requirement Levels

Requirement levels are denoted in accordance with RFC2119.

Numbers Representation

Numbers are represented in decimal format. A complementary representation in an hexadecimal or binary form can be added next to the decimal representation. e.g. 85 (55h / 01010101b).

Datatypes

The following data types are used in this document.

All multi-byte values are stored in little-endian (MSB first) order.

Name	C equivalent	Description	Encoding
Bool	Bool	True or False	True -> 0x01, False -> 0x00
String	Char []	ANSI String	Hallo Welt < NULL >
Byte	Unsigned Char	A unsigned 8 bit number	<Byte>
Integer	Unsigned Int	A unsigned 16 bit number	<H Byte><L Byte>
Long	Unsigned Long	A unsigned 32 bit number	<MSB Byte><2. Byte><3. Byte><LSB Byte>
sByte	Signed Char	A signed 8 bit number	<Byte>
sInteger	Signed Int	A signed 16 bit number	<H Byte><L Byte>
sLong	Signed Long	A signed 32 bit number	<MSB Byte><2. Byte><3. Byte><LSB Byte>
Number	float	A 32-Bit floating point number	<MSB Byte><2. Byte><3. Byte><LSB Byte>

Hardware and Physical Layer

Connectors and Pinout

RoomBus devices should use a 6P6C modular connector (commonly, but incorrectly, often referred to as RJ-12 connector).

If using a 6P6C modular connector is not feasible in a particular application, a different connector may be used.

Pinout

In case the 6P6C modular connector is used, the following pinout must be used:

Pin	Signal	Description
1	V+
2	V+
3	Bus +
4	Bus -
5	GND
6	GND

Bus Power

In case the 6P6C modular connector is used, the following specification must be obeyed:

Voltage: 24V DC +/- 20%

Maximum Current: 1A per bus line, 100mA per node

LEDs

Every bus node should be equipped with 3 LEDs, colored red, green and blue. These can either be three individual LEDs or one RGB-LED.

Red: Data Received and processed
Green: Data Transmit
Blue: Administration Mode is enabled

Data Link Layer

RoomBus uses CAN-FD with a 29-bit identifier at a fixed baud rate of 500k-baud.

Network Layer

RoomBus implements a network protocol on top of the CAN-FD identifier.

While the identifier is reserved for the network layer, the data part of the CAN-FD frame can be freely used by the application layer.

CAN-Identifier

Bit	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Data	Priority		Source Addresse							Destination Addresse							Protocol Id						Cmd			Length

Priority

The priority field defines the priority of a frame on the bus. As a result of the CAN-bus arbitration, a higher number will result in a lower priority.

Id	Priority	Description
0	Immediate	Reserved for alerts. Should not be used by applications.
1	High	For low-latency communication.
2	Normal	For normal communication.
3	Low	For file transfer, firmware updates and background tasks.

Addressing

RoomBus supports an address range of 1 - 126.

Address 0 (0h) is reserved as production default.
Address 127 (7Fh) is reserved as broadcast address.
A broadcast frame will be received and processed by all devices on the bus.

Protocol Id

The protocol id is a 6-bit (0-63) number that specifies the used application protocol.

Command (Cmd)

The use of this 3 bits is protocol specific.

Length

CAN-FD supports data lengths of 0 - 8, 12, 16, 20, 24, 32, 48 or 64 bytes while RoomBus supports 0 - 64 bytes.

The length field specifies the number of padding bytes to stuff the RoomBus packet length to a CAN-FD frame length.

Padding

CAN-Bus bit stuffing within the padding bytes must be avoided. 170 (AAh / 10101010b) should be used as a padding value.

Application Layer

Application Header

Byte	Content	Description
0 - 3	CRC 32	CRC of the application image
4 - 7	Image Size	Size of the application image
8	Major App Revision	Revision of the application
9	Minor App Revision	Revision of the application
10-69	Application Name	NULL terminated string. In case of 60 characters, NULL can be omitted
70-73	Application Main Address	Application main function entry point address
74-77	Application Data Received Address	Application data received function entry point address

All multi-byte values are stored in little-endian (MSB first) order.

Administration Mode

The administration mode is a privileged mode that must be entered for system critical configuration changes on a device.

The administration mode can be activated by sending the “Enter Administration Mode” instruction or pressing the administration button on the device.

Entering the administration mode will trigger a "System Information" message.

Application Control

Starting the application

The application will only start if the application CRC is valid.

Application Autostart Disabled

TBD

Application Autostart Enabled

The device will run the application automatically as soon as the device is powerd-on.

In case a device reset is triggered due to a watchdog timeout, division-by-zero error, or similar autostart will be automatically disabled.

Stopping the application

TBD

Application Layer Protocol Overview

The application layer defines protocols for handling different types of Applications.

Id	Protocol	Description
0	Device Management Protocol	The Device Management Protocol provides a basic set of instructions to manage basic device function and to transfer software (Bootloader) and data (File System) to or from the device.
1	Message Log Protocol	Allows to send text based messages from the device to e.g. a logging server.
2	File Transfer Protocol	Allows to access the file system of the device.
3-7	Reserved for Kernel
8	Trigger System Protocol
9	Event System Protocol	The Event System Protocol is used to trigger and report actions on a device.
10	State System Protocol
11	Value System Protocol
12	Serial Bridge Protocol	Allowes serial comunication over the BUS
13-62	Reserved
63	Protocol No. extension	Additional 8bits (following Byte) are added to the Protocol No. size.

Protocol Conventions

Every application protocol should follow the following conventions if possible:

TBD

Device Management Protocol (ID 0x00)

The device management functionality must be completely implemented on all devices.

Commands

0x00 – Device to Host Communication

0x01 – Host to Device Communication

Instruction List

Id	Instruction	Payload	Response
0x00	Heartbeat	Status	-
0x01	System Information	System Information	-
0x02	Hardware Name	String	-
0x03	Application Name	String	-
0x04	Device Name	String	-
0x05	Heartbeat request	Empty	Heartbeat
0x06	System Information Request	Empty	System Info + Hardware Name + Application Name + Device Name

0x08	Heartbeat Settings	Heartbeat parameter	-
0x09	Write Control	Control Byte	-
0x0A	Set Control	Control Byte	-
0x0B	Clear Control	Control Byte	-
0x0C	Enter Administration Mode	Password	-
0x0D	Set Device Name*	New Device Name	-
0x0E	Set Address*	New Address	-

0xF0	Diagnostics Request	Empty	Diagnostics Report
0xF1	Diagnostics Report	Diagnostics Report	Empty

0xFA	Echo	Echo Data	Echo
0xFB	Reboot*	Empty
0xFC	Erase App*	Empty
0xFD	Erase App Response*	Empty
0xFE	Bootload*	Address + Data	Bootload Response
0xFF	Bootload Response*	Address + Data Size	-

*) The device must be in administration mode to execute these instructions.

Heartbeat (0x00)

A heartbeat messages will be sent periodically to signal the devices presence on the BUS. The Heartbeat message contains the Status Byte.

System Information

Index	Data	Data Type	Size
0-3	Status	32-Bit Integer	4 Byte
4-5	Hardware Version	Integer (Major Byte, Minor Byte)	2 Byte
6-7	Kernel Version	Integer (Major Byte, Minor Byte)	2 Byte
8-9	Heartbeat Interval	Integer	2 Byte
10-11	Extended Heartbeat Interval	Integer	2 Byte
12-15	App CRC	32-Bit Integer	4 Byte
16-19	App Start Address	32-Bit Intege	4 Byte
20-23	Device Id	32-Bit Intege	4 Byte
24-27	Device Serial Number Word 0	32-Bit Intege	4 Byte
28-21	Device Serial Number Word 1	32-Bit Intege	4 Byte
22-25	Device Serial Number Word 2	32-Bit Intege	4 Byte
26-29	Device Serial Number Word 3	32-Bit Intege	4 Byte

Hardware Name / Application Name / Device Name (0x02 / 0x03 / 0x04)

The name is encoded as ASCII string. The length is limited to 60 characters.

The Name is not NULL terminated.

System Information Request (0x06)

The System Information request will trigger a Extended Heartbeat Package.

Heartbeat Settings (0x08)

The Heartbeat Settings define the interval Heartbeat messages are sent.

Data	Description	Data Type	Size
Heartbeat Interval	Time in 1 second steps, 0 = off	16-Bit Integer	2 Byte
Extended Heartbeat Interval	Time in 10 second steps, 0 = off	16-Bit Integer)	2 Byte

Messages

Status

Bit	31	30	29	28	27	26	25	24
	-	-	-	-	-	-	-	-

Bit	23	22	21	20	19	18	17	16
	-	-	-	-	-	-	-	-

Bit	15	14	13	12	11	10	9	8

	-	-	-	-	-	-	Watchdog Error	Watchdog Warning

Bit	7	6	5	4	3	2	1	0
	System Error Flag	-	Setup Mode Flag	Identify Flag	LEDs On /Off	Run App on startup	App CRC	App Running

Control

Bit	31	30	29	28	27	26	25	24
	-	-	-	-	-	-	-	-

Bit	23	22	21	20	19	18	17	16
	-	-	-	-	-	-	-	-

Bit	15	14	13	12	11	10	9	8
	-	-	-	-	-	Force App Shutdown	Reboot System	Reboot App

Bit	7	6	5	4	3	2	1	0
	System Error Flag	-	-	Identify	LEDs On /Off	Run App on startup	Check App CRC	Run App

Diagnostics Request (0xF0)

Diagnostics Report (0xF1)

Data	Data Type	Size
Bus Error Counter	24-Bit Integer	3 Byte
Last Error Code	Byte	1 Byte
App Time (Avg [us])	32-Bit Integer	4 Byte
App Time (Min [us])	32-Bit Integer	4 Byte
App Time (Max [us])	32-Bit Integer	4 Byte

Echo (0xFA)

The Echo Instruction will return a received payload back to the sender.

The intended use case for this instruction is to test the connection between devices.

Reboot* (0xFB)

This instruction will shutdown the app and restart the device.

Erase App* (0xFC)

This command will stop the execution of the application and erase the application section in the device memory.

Erase App Response* (0xFD)

This instruction will be sent by the device after the erasing process is completed.

Bootload Write* (0xFE)

This istruction code is used to send the application image to the device.

Data	Data Type	Size
Address Offset	32-Bit Integer	4 Byte
Data	n Byte	0 - 2 Byte

Bootload Response* (0xFF)

Once a Bootload Write instruction is completed, theis reponce will be sent.

Data	Data Type	Size
Address Offset	32-Bit Integer	4 Byte
Number of bytes written	Byte	1 Byte

Message Log Protocol

The message log protocol allows to send text messages for logging and diagnostic purposes from the device to a host.

Messages must be encoded as ANSI string.

The message length is limited to 60 characters.

Protocol Id: 1 (1h)

Information Flow

This protocol only generates outbound traffic from a device. Inbound traffic is ignored.

Commands

0x00 – System Message

0x01 – System Warning Message

0x02 – System Error Message

0x03 – Reserved

0x04 – Application Message

0x05 – Application Warning Message

0x06 – Application Error Message

0x07 – Reserved

Payload

Byte 0 - 3 is the system tick time. This value represents the number of milliseconds since the device started.

Byte 4 - 7 is reserved. Those bytes must be set to 0.

Byte 8 - 63 can be used for the message.

Byte	0	1	2	3	4	5	6	7	8 - 63
Data	System Tick Time				Reserved				Message

File Transfer Protocol

The file transfer protocol allows access to the file system on the device.

Protocol Id: 2 (2h)

Information Flow

This protocol generates outbound traffic from the device on request.

Commands

0x00 – Host to Device Communication

0x01 – Device to Host Communication

0x02 – Reserved

0x03 – Reserved

0x04 – Data Transfer from Device

0x05 – From Device Ack

0x06 – Data Transfer to Device

0x07 – To Device Ack

Command (0x00)

Code	Name	Payload	Response	Description
0x00	List content	Path	File Info
0x01	Get space Information	Path		Not implemented
0x02	Get File Information	Path		Not implemented

0x08	Make File	Path
0x09	Delete File	Path

0x20	Start File Read	Path
0x21	End File Read	Path

0x30	Start File Write	Path
0x31	End File Write	Path

Response (0x01)

Code	Name	Payload
0x00	File Info	File Info

0x20	Start File Read Acknowledgment	Path

0x30	Start File Write Acknowledgment
0x31	Complete File Write Acknowledgment

File Info Response

Byte
0	1	2	3	4	5	6	7-57	58-62
Code (0x00)	Status	Type	File Size				Path	Reserved

Status

Code	Name	Description
0x00	ftp_rsps_ok
0x01	ftp_rsps_pathInvalid

0x20	ftp_rsps_writeSuccessful
0x21	ftp_rsps_writeCrcError
0x22	ftp_rsps_writeSequencingError

0x30	ftp_rsps_readSuccessful
0x31	ftp_rsps_readCrcError
0x32	ftp_rsps_readSequencingError

Data Transfer from Device (0x04) / Data Transfer to Device (0x06)

Byte
0	1	2	3	4-n
Data Offset				Data

From Device Acknowledgment (0x05) / To Device Acknowledgment (0x07)

Byte
0
Status

Trigger System Protocol

The trigger system protocol allows to trigger an action on a device.

A device can emit triggers, called a trigger signal, and consume triggers, called a trigger slot.

Protocol Id: 8 (8h)

Information Flow

This protocol accepts inbound traffic and generates outbound traffic.

Commands

0x00 – Trigger

0x01 – Reserved

0x02 – Reserved

0x03 – Reserved

0x04 – Trigger Signal Information Report

0x05 – Trigger Slot Information Report

0x06 – Trigger Signal Information Request

0x07 – Trigger Slot Information Request

Trigger

A trigger command holds a list of trigger channels.

1 to 32 triggers can be sent in one message.

Byte	n	n+1
Data	Trigger Channel Number

Trigger Signal Information Request / Trigger Slot Information Request

Upon receipt of a information request, the device will respond with a information report.

The payload of the information request can either contain a list of the requested trigger channel numbers or be left empty.

In case of an empty payload, a trigger information report for all configured trigger signals or slots will be returned respectively.

Byte	n	n+1
Data	Trigger Channel Number

Trigger Signal Information Report

Byte	0	1	2+n
Data	Trigger Channel Number		Channel Description

Trigger Slot Information Report

Byte	0	1	2+n
Data	Trigger Channel Number		Channel Description

Event System Protocol

The event system protocol allows to enable an action for a defined time on a device.

Protocol Id: 9 (9h)

Information Flow

This protocol accepts inbound traffic and generates outbound traffic.

Commands

0x00 – Event

0x01 – Reserved

0x02 – Reserved

0x03 – Reserved

0x04 – Event Signal Information Report

0x05 – Event Slot Information Report

0x06 – Event Signal Information Request

0x07 – Event Slot Information Request

Event Slot

Byte	n	n+1
Data	Event Channel Number

Event Signal Information Request / Event Slot Information Request

Upon receipt of a information request, the device will respond with a information report.

The payload of the information request can either contain a list of the requested event channel numbers or be left empty.

In case of an empty payload, a event information report for all configured event signals or slots will be returned respectively.

Byte	n	n+1
Data	Event Channel Number

Event Signal Information Report

Byte	0	1	2	3	4-n
Data	Event Channel Number		Interval		Channel Name

Event Slot Information Report

Byte	0	1	2	3	4-n
Data	Event Channel Number		Timeout		Channel Name

State System Protocol

The state system protocol allows the distribution of a device state on the system.

Protocol Id: 10 (Ah)

Information Flow

This protocol accepts inbound traffic and generates outbound traffic.

Commands

0x00 – State Report

0x01 – State Request

0x02 – Reserved

0x03 – Reserved

0x04 – State Signal Information Report

0x05 – State Slot Information Report

0x06 – State Signal Information Request

0x07 – State Slot Information Request

State Report

Byte	n	n+1	n+2
Data	State Channel Number		State Code

State Code

Code	Name	Description
0	Off
1	On
2	Transitioning	State is transitioning from On to Off
3	Undefined / Error	State is unclear or error
4-255	Reserved

State Request / State Signal Information Request / State Slot Information Request

Upon receipt of a request, the device will respond with a report.

The payload of the request can either contain a list of the requested event channel numbers or be left empty.

In case of an empty payload, a report for all configured signals or slots will be returned respectively.

Byte	n	n+1
Data	State Channel Number

State Signal Information Report

Byte	0	1	2+n
Data	State Channel Number		Channel Name

State Slot Information Report

Byte	0	1	2+n
Data	State Channel Number		Channel Name

Value System Protocol

The value system protocol allows the distribution of a device value on the system.

Protocol Id: 11 (Bh)

Information Flow

This protocol accepts inbound traffic and generates outbound traffic.

Commands

0x00 – Value Report

0x01 – Value Request

0x02 – Value Command

0x03 – Reserved

0x04 – Value Signal Information Report

0x05 – Value Slot Information Report

0x06 – Value Signal Information Request

0x07 – Value Slot Information Request

Value Report

Byte	0	1	2	3	4	5
Data	Value Channel Number		Value

Value Command

Byte	0	1	2	3	4	5	6
Data	Value Channel Number		Operation Id	Value

Operation

Id	Description	Limit enforcement	Datatype
0x00	Set value to minimum	-	-
0x01	Set value to maximum	-	-
0x02	Invert / Complement	-	-


0x10	Set value	Reject	Long
0x11	Set value	Clamp	Long

0x20	Add value	Reject	Long
0x21	Add value	Clamp	Long

0x30	Subtract value	Reject	Long
0x31	Subtract value	Clamp	Long


0x40	Set value	Reject	Number
0x41	Set value	Clamp	Number

0x50	Add value	Reject	Number
0x51	Add value	Clamp	Number

Value Signal Information Request / Value Slot Information Request

Upon receipt of a information request, the device will respond with a information report.

The payload of the information request can either contain a list of the requested event channel numbers or be left empty.

In case of an empty payload, a information report for all configured signals or slots will be returned respectively.

Byte	n	n+1
Data	Value Channel Number

Value Signal Information Report

Byte	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14+n
Data	Value Channel Number		Interval		RO	UoM	Minimum				Maximum				Channel Name

Value Slot Information Report

Byte	0	1	2	3	4	5	6+n
Data	Value Channel Number		Timeout		Unit of Measurement		Channel Name

Unit of Measurements

For data type definitions, see chapter "Datatypes"

UoM Code	Symbol	Description	Data Type	Note
0x00		Generic Long	Long
0x01		Generic Number	Number

0x10		Absolute Time	Long	Unix time as 32 bit unsigned int
0x11		Time of Day	Long	Milliseconds since midnight
0x12		Date	Long	tbd
0x13	s	Relative Time	Number
0x14	°C	Temperature	Number
0x15	%	Rel. Humidity	Number
	kPa	Pressure	Number
	V	Voltage	Number
	A	Current	Number
	W	Power	Number
		Power Factor	Number
	Hz	Frequency	Number
	kWh	Energy	Number
	Ω	Resistance	Number
	F	Capacitance	Number
	N	Force	Number
	kg	Weight	Number
	m	Length	Number
	m/s	Speed	Number

Serial Bridge Protocol (ID 0x0C)

Commands

0x00 – Data

0x01 – Reserved

0x02 – Reserved

0x03 – Reserved

0x04 – Port Info Report

0x05 – Port Info Request

0x06 – Reserved

0x07 – Reserved

Data (0x00) OLD

Byte
0	1	2	3	4	5	6	7	8-n
Source Port No				Destination Port No				Data

Data (0x00)

Byte
0	1	2-n
Port	Status	Data

Port Info Report (0x04)

Byte
0	1-n
Number of Ports	Port Information

Port Information

Code	Type	Description
0x00	UART (Serial Port)
0x01	I2C

Port Info Request (0x05)

This command will return a list of available ports. The Data field is empty.