N2 is the RS-485 field bus of Johnson Controls Metasys building automation systems. The Weble universal gateway N2 driver implements the N2 Open variant, the ASCII protocol spoken by JCI FX controllers (FX05/06/07/14/15/16 with the N2 Open option), UNT, AHU, VAV and VMA controllers, and by third-party N2 Open devices.
The driver works in two roles:
The legacy N2 bus variant used by the DX-9100, TC-9100 and XT-9100 controllers (memory reads by item) is not supported.
N2 Open runs on RS-485 at a fixed 9600 baud, 8 data bits, no parity, 1 stop bit. Connect the bus to an RS-485 port of the gateway (built-in port or USB adapter). Serial parameters are fixed by the protocol and cannot be changed.
The N2 bus allows one master only. In master mode, the gateway must be the only master on the bus; disconnect or disable the NCM/NAE. In slave mode, the gateway's N2 address must not be used by another device on the bus.
master and pick the RS-485 interface in Serial Port.10000 ms for a start.%n2:AI1 for analog input 1 of the default device.At connection the driver sends an Identify command to every device present in the addresses and logs device N identified, type XX, then starts polling.
slave.%n2:AI1, %n2:BI1, %n2:ADF1.The gateway also answers for every other device number present in its addresses: %n2:21-AI1 is served as analog input 1 of device 21.
Right-click in the address grid and choose Monitor to open a live view of every frame sent and received on the bus, with timestamp, direction and device. The monitor runs for at most 5 minutes per session and is available in both roles. Use it to check wiring, addresses and object numbering.
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this gateway instance. |
| Cluster ID | cluster | Cluster identifier. Use 0 for single-gateway setups. |
| Type | json.type | master: the gateway polls and commands N2 devices. slave: the gateway emulates N2 Open devices. Default: master. |
| Serial Port | json.serialPort | The RS-485 interface, picked from the auto-complete list of detected USB/serial interfaces. 9600 baud 8N1 fixed. |
| Default N2 device / N2 address (this box) | json.deviceAddress | Master: device used by addresses that omit the device number. Slave: the gateway's own N2 address. 1 to 255. Default: 1. |
| Object offset | json.objectOffset | Added to the object number sent on the bus. Use -1 when the device documentation numbers objects from 1 while the bus counts from 0. Default: 0. |
| Read loop delay (ms or cron) | json.readLoopDelay | Master only. Default polling interval of the addresses, in milliseconds, or a cron expression. Each address can override it. Default: 10000. |
| Request timeout (ms) | json.requestTimeout | Master only. Maximum wait for a response. After a timeout the device is skipped for 10 seconds. JCI masters use 200 ms. Default: 500. |
| Idle timeout (ms) | json.idleTimeout | Master only. Pause between two requests on the bus. Default: 0. |
| Device type (Identify) | json.deviceType | Slave only. Two hexadecimal characters returned to the master's Identify command. 10 = non-JCI device. Default: 10. |
| (JSON only) | json.errorRetries | Master. Number of consecutive errors tolerated on an address before its status shows the error. 0 reports the first error. Default: 2. Not shown in the form; edit the gateway JSON to change it. |
{
"type": "master",
"serialPort": "/dev/extcomm/1/0",
"deviceAddress": 5,
"objectOffset": 0,
"readLoopDelay": 10000,
"requestTimeout": 500,
"idleTimeout": 0
}
%n2:[device-]TYPEobject[.attribute]
| Part | Meaning |
|---|---|
device |
N2 device address, 1 to 255. Optional: when omitted, the gateway's Default N2 device is used. |
TYPE |
Object type: AI, BI, AO, BO, ADF, ADI or DB (uppercase). |
object |
Object number, 0 to 255, as counted on the bus (see Object offset). |
.attribute |
Attribute number. Optional: when omitted, the value attribute of the type is used (3 for AI/AO, 2 for the other types). |
Examples:
%n2:5-AI1 — value of analog input 1 of device 5 (float)%n2:5-BO2 — state of binary output 2 of device 5 (bit of the status byte)%n2:ADF10 — internal float 10 of the default device%n2:5-AI1.11 — attribute 11 of analog input 1, the high alarm limitThe address editor builds the name from four fields: Device, Type, Object and Attribute. The attribute list shows the known attributes of the selected type, with the default one marked.
A read or write on a valid
%n2:address that does not exist yet creates it automatically in the gateway.
| Type | Label | Value attribute | Attributes |
|---|---|---|---|
| AI | Analog input | 3 (float) | 1 Configuration, 2 Status, 3 Value, 4–7 Linear range 1–4, 8 Low alarm limit, 9 Low warning limit, 10 High warning limit, 11 High alarm limit, 12 Differential, 13 Filter weight, 14 Offset |
| BI | Binary input | 2 (state bit) | 1 Configuration, 2 Status (state), 3 Debounce, 4 Accumulator |
| AO | Analog output | 3 (float) | 1 Configuration, 2 Status, 3 Value, 4 Low linear range, 5 High linear range |
| BO | Binary output | 2 (state bit) | 1 Configuration, 2 Status (state), 3 Minimum on time, 4 Minimum off time, 5 Max cycles per hour, 6 Interstage on delay, 7 Interstage off delay |
| ADF | Internal float | 2 (float) | 1 Status, 2 Value |
| ADI | Internal integer | 2 (int16) | 1 Status, 2 Value |
| DB | Internal byte | 2 (uint8) | 1 Status, 2 Value |
Each known attribute has a default data type: floatBE for analog values and limits, int16BE for integer values, times and counters, uint8 for configuration and status bytes, bit for binary states. Attributes not in this list are decoded as uint8 unless Datatype is forced.
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The N2 address, see 3.1. |
| Description | description | Optional description. |
| Polling (ms or cron, 0 = never) | json.readLoopDelay | Master only. Polling interval of this address, in milliseconds or as a cron expression. Empty: the gateway's Read loop delay. 0: never polled, read on demand only. |
| Datatype | json.datatype | auto (from type and attribute), floatBE, int16BE, uint16BE, int8, uint8 or bit. Force it only for a non-standard attribute. Default: auto. |
| Status bit | json.bit | BI/BO state only. Bit of the status byte that holds the state, 0 to 7. Default: 6. |
| Scale | json.scale | Read: value × scale. Write: value ÷ scale. Hidden for binary states. |
| Offset | json.offset | Read: + offset. Write: − offset. Hidden for binary states. |
| COV | json.cov | Master polling only. Empty: a new value is emitted only when it changes. 0: emitted at every read. Greater than 0: polled values are emitted only when the change exceeds this amount. Cron-scheduled reads always emit. |
| Log | log | Logging mode: never, on update, always, or a fixed duration. |
| Property | Value |
|---|---|
| Readable | Yes — master: Read Field on the bus (polling, manual read, after insert); slave: last served value |
| Writable | Yes — numbers on every type, null on AI/BI/AO/BO to release an override |
| Routable | Yes |
| Loggable | Yes |
Each address is read with a Read Field command at its polling interval. One request is on the bus at a time, with the optional Idle timeout between requests. The raw value is decoded with the address data type, then scaled: value × scale + offset.
A device that does not answer within Request timeout is skipped for 10 seconds; reads and writes on that device fail immediately with device offline during that window, without changing the address status. An address status shows the error only after errorRetries consecutive errors (third error by default).
The command sent depends on the address:
| Address | Written value | Command |
|---|---|---|
| AI, BI, AO, BO, value attribute | number | Override — the point is forced and stays overridden |
| AI, BI, AO, BO, value attribute | null |
Release — removes the override |
| ADF, ADI, DB value | number | Write Field |
| Any other attribute | number | Write Field |
Values are converted with (value − offset) ÷ scale; when the data type needs an integer, the result is rounded so that routed values work without a transformation. Twenty milliseconds after a successful write, the driver reads the address back to refresh its value. If the read-back fails, the write reports write succeeded, but reading back failed.
Writing to an AI/BI/AO/BO value is an Override: the controller's own logic no longer drives the point until you write
nullto release it. Use ADF/ADI/DB points or non-value attributes when you want a plain write.
In slave mode the gateway answers the master's requests for its own N2 address and for every device number present in its addresses:
NAK 11 (attribute unused), so the master sees an error rather than a false zero.Values written locally by routes, the API or the interface are validated and rounded by the address data type before being served. On restart, the last stored value of each address is served again.
{ "type": "master", "serialPort": "/dev/extcomm/1/0", "deviceAddress": 5,
"objectOffset": 0, "readLoopDelay": 10000, "requestTimeout": 500 }
| Address | JSON | Purpose |
|---|---|---|
%n2:AI1 |
{ "cov": 0.1 } |
Supply temperature, emitted when it moves by 0.1 |
%n2:BO2 |
{ "bit": 6 } |
Fan command; write 1 or 0 to override, null to release |
%n2:ADF10 |
Setpoint stored as internal float; writes are plain Write Field | |
%n2:AI1.11 |
{ "readLoopDelay": 0 } |
High alarm limit of AI1, read on demand only |
{ "type": "master", "serialPort": "FTDI-FT232R_USB_UART-a1b2c3", "deviceAddress": 1,
"objectOffset": -1, "readLoopDelay": "0 */5 * * * *", "requestTimeout": 200,
"idleTimeout": 50, "errorRetries": 0 }
%n2:3-ADI1 is sent on the bus as object 0 of device 3; %n2:4-AO1 and %n2:4-BI1 read device 4. Every point is read every 5 minutes and emitted at each read.
{ "type": "slave", "serialPort": "/dev/ttyUSB0", "deviceAddress": 20, "deviceType": "10" }
| Address | Purpose |
|---|---|
%n2:AI1 |
Served as a float; feed it with a route from a Modbus meter |
%n2:BI1 |
Served as a state in bit 6 of the status byte |
%n2:ADF1 |
The NAE can write it; the new value appears on the address and can be routed |
%n2:21-AI1 |
Served as device 21 |