RS-485 roles

Verified on Edge Server release 5.4.0.

A Controller has one RS-485 port. The port has one role at a time.

Defaults

A new Controller is in the Modbus Slave role. A factory reset sets it back to Modbus Slave.

A Controller that has never had a role set changes to BACnet MS/TP when a BACnet master speaks on the bus. See Auto-detection under BACnet MS/TP below.

Wire the port

The RS-485 port is connector J14: an M12 A-coded 5-contact receptacle. The contacts follow the CANopen and DeviceNet assignment.

1. Use two-wire half-duplex RS-485. On a half-duplex bus, only one device can send at a time.
2. Connect A to A and B to B. Some vendors swap the A and B names. Check the device manual.
3. Connect a common ground (contact 3) where the device needs a reference.
4. Terminate the bus at its two ends only.
5. Connect the cable shield at one end only, away from the Controller.
6. Do not use V_OUT to power a device that has its own supply.

The bus has no password. Any device on the bus can read and control the Controller. Protect access to the bus and to any network adapter on it.

Every device on one bus uses the same baud, parity and stop bits. A repeater does not let you mix them. Give each device its own address, 1 to 247.

Change the role

The steps are the same in the web app and the desktop app.

1. Select Control in the sidebar.
2. Select the Controller.
3. Open Controller settings, then the Fieldbus tab.
4. Under RS-485 port, select the role.

The Wireless tab can also take the port. When the backhaul is Ethernet / RS-485, the port is in the Modbus Slave role, and the Fieldbus result shows Used by the backhaul. You cannot add Modbus devices or use BACnet on the port while it carries the backhaul.

A role change stops the work of the old role:

• To Modbus Slave or BACnet MS/TP: the Controller stops polling. It keeps the master configuration. When you go back to Modbus Master, polling starts again with no new configuration.
• To Modbus Master or BACnet MS/TP: the Controller stops answering a Modbus master.
• A role change cancels queued bus work.

If a role change fails, the Controller stays on its old role. If it fails again, remove power from the Controller, then apply power again. A restart from the app does not help. If a role cannot start at boot, the Controller goes back to Modbus Slave.

Modbus Slave

In the Modbus Slave role, the Controller works with no app, no account and no gateway. The master reads and controls it through the register map.

• Function codes: 0x03 read holding, 0x04 read input, 0x06 write single, 0x10 write multiple. Other codes answer ILLEGAL_FUNCTION.
• Registers are 16-bit, big-endian on the wire, addressed from 0.
• Broadcast (address 0) is not supported. The Controller ignores it.
• Reserved registers read as 0. A write to a reserved register answers ILLEGAL_DATA_ADDRESS.

Set the address and line format

Set the Controller address in the app:

1. On the Fieldbus tab, select Modbus Slave.
2. Select Open Modbus setup.
3. Select Edit configuration.
4. Under Controller role, select Slave / expose controller.
5. Under RS-485 bus, set Controller address, Baud, Parity and Stop bits.
6. Select Review changes.
7. Select Confirm and apply.

A master can also set the address and the role:

The Controller saves the change before it applies it. A write to 0x0001 also turns off BACnet auto-detection.

A write of 0 to 0x0001 ends the slave session. The Controller becomes a master and stops answering your requests.

Register blocks

Addresses at 0x0440 and above answer ILLEGAL_DATA_ADDRESS.

Per-channel registers

Each output has a 16-register block. Add the offset to 0x0010 + n × 0x10, where n is the channel, 0 to 3.

Some terms in these tables:

• A held output stays on with continuous DC drive until a command turns it off.
• A DC pulse valve is a latching valve. A short pulse moves it, and it then stays in place with no power. Continuous DC drive can burn it.
• The latch stroke is the length of the pulse that moves a DC pulse valve.

Holding registers (0x03, 0x06, 0x10):

A read of +0 to +2 gives the last command that the Controller applied, not the live state.

Input registers (0x04):

Commission an output before you command it. Write the device type to offset +3. When the outputs switch DC, every type except the DC pulse valve needs bit 15 set, unless offset +6 already reads 1.

Device block (0x00E0-0x00EF)

To set the clock, write UNIX time in seconds, UTC:

1. Write the high word to 0x00E4 with function 0x06.
2. Write the low word to 0x00E3 with function 0x06.

Do not write both words in one 0x10 request. The Controller refuses it, because the low word lands first. The Controller also refuses a time before 2020. Schedules do not run until the clock is set.

When the protocol version is 1 or more, check that the identity magic is 0x4743.

Exceptions

An interlock is a safety rule that blocks a command. Break-before-make is the interlock that turns one output off before a paired output turns on. SLAVE_DEVICE_FAILURE is an interlock at work, not a bus error.

An Edge Server on the slave port

An Edge Server reaches a Controller in the Modbus Slave role through an RS-485-to-Ethernet adapter on the site network. Over this wired link, the Edge Server reads the Controller and switches its outputs. A command sent this way shows transport rs485 in the API.

Use one master on the bus. Do not connect an Edge Server and Home Assistant as two masters on one bus.

With Home Assistant as the master, the Controller stays a slave. Home Assistant then polls the library devices on the same bus itself, each at its own address. Every device must use the Controller's line format.

Modbus Master

In the Modbus Master role, the Controller polls the devices on the bus and keeps the readings. The Controller polls the devices without the Edge Server. The Edge Server stores the configuration, sends changes over LoRaWAN and publishes the readings.

1. On the Fieldbus tab, select Modbus Master.
2. Select Open Modbus setup.
3. Select Edit configuration.
4. Under Controller role, select Master / poll devices.
5. Under RS-485 bus, set Baud, Parity and Stop bits for the whole bus.
6. Add the devices.

The Configure Modbus devices guide gives every step.

What the master role changes:

• The Controller no longer answers a Modbus master.
• A Modbus point write needs this role. In another role, the write answers 422 with reason MODBUS_MASTER_MODE_REQUIRED.
• A Modbus point write goes over LoRaWAN only. The wired link cannot carry it.
• The Controller retries a read that times out or fails its CRC check. It does not retry a Modbus exception.

If a device ships with a different line format, change the device first. For example, an Apogee quantum sensor ships at 19200 8E1.

BACnet MS/TP

The Controller can be a BACnet MS/TP device on the RS-485 port. An MS/TP trunk is the bus that connects the BACnet devices.

Auto-detection

A Controller that has never had a role set listens for BACnet. Every MS/TP frame starts with 0x55 0xFF. A Modbus request never starts with these bytes. After two such preambles from a BACnet master, the Controller changes to BACnet MS/TP and keeps that role after a restart.

When you set a role, in the app or at holding register 0x0001, the Controller stops this detection for good.

Set up BACnet MS/TP

1. On the Fieldbus tab, select BACnet MS/TP.
2. Turn on Enable BACnet. It is off by default. When it is off, the Controller publishes no points.
3. Under Connection, select MS/TP (RS-485).
4. Set Device Instance, 0 to 4194303. It must be unique on your BACnet network.
5. Set MAC address (0–127), Baud and Max master (1–127). Use the values of your MS/TP trunk.
6. Select the points to publish.
7. To let the building system control outputs, turn on Allow BMS writes to outputs.

Max master is the highest MAC address of a BACnet master on the trunk. The Controller looks for other masters up to this address only.

The app offers 9600, 19200, 38400 and 76800 baud. The Controller applies the role and the settings when it next receives its configuration from the app.

With no point list, the Controller uses device instance 300001 and MAC address 1. It publishes this default list of 32 objects:

A configured point list replaces the default list. The Controller keeps the BACnet settings through a restart and a power loss (firmware 5.3.0 or newer). A factory reset clears them.

USB App

The USB App role keeps the port for the desktop app. The desktop app connects through a USB-to-RS-485 adapter from the Controller's Control page. Disconnect the adapter before you set the port back to Modbus or BACnet.

Read and set the Modbus mode through the API

These routes need Edge Server 5.4.2 or later. They are standard routes and need no setting. The app uses other routes, so the steps above work on every Edge Server.

The API calls the role mode. The mode is the Modbus mode that you want: slave or master. It does not show BACnet MS/TP or USB App. A Controller in the BACnet MS/TP or USB App role still shows its last Modbus mode.

GET /sensing/v1/controllers/{serial}/modbus/config returns { "config": { ... } }:

• config.config.mode is slave or master.
• config.config.bus holds slave_address, baud, parity and stop_bits.
• config.etag and config.desired_version identify this version. Keep them for the change.

A Controller with no configuration returns the default: mode slave, address 1, 9600 baud, no parity, 1 stop bit.

An organization admin can change the mode with PATCH /control/v1/controllers/{serial}/modbus/config and the operation {"op": "set_mode", "mode": "master"}. Send the etag in the If-Match header. Send desired_version as base_desired_version. BACnet MS/TP and USB App are not set through this route.

SERIAL=<serial>
ETAG=<config.etag from the GET>
VERSION=<config.desired_version from the GET>
curl -sk -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "If-Match: \"$ETAG\"" \
  -d '{"base_desired_version": '"$VERSION"', "operations": [{"op": "set_mode", "mode": "master"}]}' \
  "https://<your Edge Server address>:8443/control/v1/controllers/$SERIAL/modbus/config?wait=30"

The mode change is an operation. The Edge Server sends it to the Controller over LoRaWAN, and this can take minutes. A 202 answer means the operation is still running. Follow poll until operation.status is applied. The port changes only then.

The Controllers reference lists the answers and errors.

Next

• Configure Modbus devices
• Controllers