The SAIA driver communicates with Saia-Burgess PCD controllers (now SBC / Honeywell) using the Ether S-Bus protocol over UDP. It is similar in concept to Modbus — the gateway acts as a client that reads and writes registers, flags, inputs, and outputs on the PCD controller.
The driver supports:
- 4 address types: Registers (16-bit data words), Flags (binary), Inputs (binary, read-only), and Outputs (binary).
- Rich datatype library: over 40 datatypes including integers (8/16/32/64-bit), floats, doubles, BCD, mod10000, hex, ASCII — in big-endian, little-endian, swapped-words, and swapped-bits variants.
- Polling: per-address polling with millisecond intervals or cron expressions.
- Scale and offset: per-address value transformation (
value = raw × scale + offset). - SAIA CSV/XLS import: import address lists directly from SAIA PG5 project export files.
¶ 1. Getting started
¶ 1.1 Gateway configuration
Create a new gateway and select the SAIA driver. Configure:
- Host: the IP address of the Saia PCD controller.
- Port: the Ether S-Bus UDP port (default:
5050). - Unit ID: the S-Bus station number of the PCD (similar to Modbus slave ID). Default:
1.
¶ 1.2 Inserting addresses
The driver organizes addresses into 4 tabs:
- Registers — 16-bit data words (
%saia_reg:<number>). Used for analog values, counters, setpoints. Support multi-register datatypes (32-bit, 64-bit, float, etc.) by spanning consecutive registers. - Flags — binary data points (
%saia_flag:<number>). Used for boolean states, status bits. - Inputs — binary inputs (
%saia_input:<number>). Typically read-only physical inputs on the PCD. - Outputs — binary outputs (
%saia_output:<number>). Controllable digital outputs on the PCD.
Insert an address by selecting the appropriate tab and entering the register/flag/input/output number.
For registers, you can also specify a start bit to read a specific bit range within a register (e.g. %saia_reg:100.8 reads from register 100, starting at bit 8).
¶ 1.3 Importing from SAIA PG5
The driver supports importing address lists from SAIA PG5 project export files (CSV or XLS format):
- Right-click on the gateway and select SAIA csv/xls file import.
- Select the exported CSV or XLS file from PG5.
- The driver parses the file and creates addresses automatically with their descriptions and default polling.
The import recognizes the following tags in the CSV: R (register), F (flag), I (input), O (output).
¶ 2. Gateway parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this SAIA gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Host | host | IP address of the Saia PCD controller. Default: 192.168.1.99. |
| Port | port | Ether S-Bus UDP port. Default: 5050. |
| Unit ID | unitId | S-Bus station number of the PCD controller (0-255). Default: 1. |
| Address Offset | addressOffset | Integer offset applied to all address numbers. Similar to the Modbus register offset. Default: 0. |
| Request Timeout (ms) | requestTimeout | Maximum time in milliseconds to wait for a response from the PCD before triggering a timeout error. Default: 3000. |
¶ 2.1 Gateway JSON example
{
"host": "192.168.1.99",
"port": 5050,
"unitId": 1,
"addressOffset": 0,
"requestTimeout": 3000
}
¶ 3. Addresses
¶ 3.1 Address format
| Type | Format | Example | Description |
|---|---|---|---|
| Register | %saia_reg:<number> |
%saia_reg:100 |
16-bit data register |
| Register + bit | %saia_reg:<number>.<startBit> |
%saia_reg:100.8 |
Register with bit offset (for multi-register datatypes) |
| Flag | %saia_flag:<number> |
%saia_flag:200 |
Binary flag (0 or 1) |
| Input | %saia_input:<number> |
%saia_input:0 |
Binary input (read-only) |
| Output | %saia_output:<number> |
%saia_output:0 |
Binary output |
¶ 3.2 Address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The SAIA address (register/flag/input/output number). |
| Description | description | Optional description. |
| Polling | polling | Read frequency. Accepts milliseconds (e.g. 1000) or cron expressions (e.g. */5 * * * * *). Multiple schedules can be combined with ;. Default: 1000. |
| Datatype | datatype | The data encoding format (see section 3.3). Only visible for registers (flags/inputs/outputs are always bit). Default: int16BE. |
| Scale | scale | Multiplication factor applied to the raw value. Default: 1. Only visible for registers. |
| Offset | offset | Value added after scaling. Default: 0. Only visible for registers. |
| Log | log | Logging mode: never, on update, always, or a duration in milliseconds. |
¶ 3.3 Datatypes
The SAIA driver supports a comprehensive set of datatypes for interpreting register values:
¶ Integer types
| Datatype | Size | Range | Description |
|---|---|---|---|
int8 |
8-bit | -128 to 127 | Signed byte |
uint8 |
8-bit | 0 to 255 | Unsigned byte |
int16BE |
16-bit | -32768 to 32767 | Signed integer, big-endian (default) |
int16LE |
16-bit | -32768 to 32767 | Signed integer, little-endian |
uint16BE |
16-bit | 0 to 65535 | Unsigned integer, big-endian |
uint16LE |
16-bit | 0 to 65535 | Unsigned integer, little-endian |
int32BE |
32-bit | ±2.1 billion | Signed 32-bit, big-endian (spans 2 registers) |
int32LE |
32-bit | ±2.1 billion | Signed 32-bit, little-endian |
uint32BE |
32-bit | 0 to 4.3 billion | Unsigned 32-bit, big-endian |
uint32LE |
32-bit | 0 to 4.3 billion | Unsigned 32-bit, little-endian |
int64BE / int64LE |
64-bit | ±9×10¹⁵ | Signed 64-bit (spans 4 registers) |
uint64BE / uint64LE |
64-bit | 0 to 9×10¹⁵ | Unsigned 64-bit |
¶ Floating point
| Datatype | Size | Description |
|---|---|---|
floatBE / floatLE |
32-bit | IEEE 754 single precision (spans 2 registers) |
doubleBE / doubleLE |
64-bit | IEEE 754 double precision (spans 4 registers) |
¶ BCD (Binary Coded Decimal)
| Datatype | Size | Range | Description |
|---|---|---|---|
bcd8 |
8-bit | 0 to 99 | BCD encoded byte |
bcd16BE / bcd16LE |
16-bit | 0 to 9999 | BCD encoded 16-bit |
bcd32BE / bcd32LE |
32-bit | 0 to 99999999 | BCD encoded 32-bit |
¶ Special types
| Datatype | Size | Description |
|---|---|---|
bit |
1-bit | Binary value (0 or 1). Used for flags, inputs, outputs. |
mod10000_2_BE / _LE |
32-bit | Two registers encoded as value = reg1 + reg2 × 10000 |
mod10000_3_BE / _LE |
48-bit | Three registers with mod 10000 encoding |
mod10000_4_BE / _LE |
64-bit | Four registers with mod 10000 encoding |
hex_1 to hex_8 |
16-512 bit | Raw hexadecimal value (1 to 8 registers) |
ascii_1 to ascii_8 |
16-512 bit | ASCII string (1 to 8 registers) |
¶ Byte/word/bit order variants
For any multi-byte datatype, additional variants are available:
_sw(swapped words) — reverses the 16-bit register order. For example,int32BE_swreads the two 16-bit registers in reversed order._sb(swapped bits) — reverses the bit order within each byte.
¶ 3.4 Value calculation
For register addresses, the final value is:
value = raw × scale + offset
This is useful for converting raw register values to engineering units. For example, a register storing temperature in tenths of degrees with scale = 0.1 and offset = 0 converts 225 to 22.5°C.
¶ 4. S-Bus protocol commands
The driver uses the following Ether S-Bus commands:
| Command | Code | Description |
|---|---|---|
| Read Flags | 2 | Read binary flag values |
| Read Inputs | 3 | Read binary input values |
| Read Outputs | 5 | Read binary output values |
| Read Registers | 6 | Read 16-bit register values |
| Write Flags | 11 | Write binary flag values |
| Write Outputs | 13 | Write binary output values |
| Write Registers | 14 | Write 16-bit register values |
Note: Inputs are read-only — the driver does not support writing to inputs (command 3 only).
¶ 5. Address properties
| Property | Registers | Flags | Inputs | Outputs |
|---|---|---|---|---|
| Readable | Yes | Yes | Yes | Yes |
| Writable | Yes | Yes | No | Yes |
| Routable | Yes | Yes | Yes | Yes |
| Loggable | Yes | Yes | Yes | Yes |