UART Interface¶

The UART management interface allows communication with and configuration of the W-Modbus module. The interface is comprised of two digital signals (V_DD max):

TX - Transmitter Signal
RX - Receiver Signal

Connect the UART cable's RX to the UART_MGMT_TX and TX to UART_MGMT_RX pin. Pin assignments can be found here.

Interface Description¶

Configuration¶

The UART management interface has the following communication parameters:

Baudrate	Parity	Stop bits
`115200`	`None`	`1`

Timing requirements¶

Each UART frame is separated by 100 ms of silence on the bus. Sending frames with less than 100 ms in between the first frame's end and the second frame's start will result in unexpected results.

UART commands¶

UART commands and responses are comprised of ASCII characters. The user should enter each command separately by considering the timing requirements. Commands are split into two categories: Read and Write commands.

The usage example further down shows how the APP_MODE register is read.

Syntax¶

UART commands start with either the character r or w, which respectively denote the read or write command operation. The first character is followed by the separator :, and a register name (see the list of registers). In the case of write commands, the separator can be used again at this point to specify additional write parameters. Finally, the command is terminated with a carriage return followed by a new line: "\r\n".

Additionally, the syntax has the following properties:

Numeric values are always interpreted and written in decimal form.
All text is case insensitive, meaning commands can also start with R or W. This also means that any register name can be written as ex. REG_NAME, or reg_name, or even rEg_NaMe. For the sake of consistency, we specify the command operation in lower case and the register name in upper case.

Reads¶

Read commands have the following format, where REG_NAME is a placeholder for any readable register (see the list of registers):

r:REG_NAME\r\n

When a read command is successful, the response follows the format below, where REG_NAME is a placeholder for any readable register, and VALUE is a placeholder for the value read from the register:

ok:REG_NAME:VALUE\r\n

Some registers have more than one value, each one separated (like RS485_CONFIG):

ok:REG_NAME:VALUE1:VALUE2:VALUE3\r\n

It is also possible for a register to have no values, as can be the case with SERVER_ADDRESSES when no Modbus devices are detected:

ok:REG_NAME:\r\n

A real example of multiple values when reading (and writing) can be seen in the section about the RS485_CONFIG register.

Writes¶

Write commands have the following format, where REG_NAME is a placeholder for any writable register (see the list of registers), and PARAM can be any valid write parameter:

w:REG_NAME:PARAM\r\n

Some registers take more than one parameter:

w:REG_NAME:PARAM1:PARAM2\r\n

In the case of a successful write command, the response should reflect exactly the content of the original request, but instead leading with an ok instead of a w. See the examples further down for examples.

Responses and errors¶

Responses follow almost the same format as reads and writes, but instead begin with either ok: when the command was successful, otherwise error:. Error messages are generated when the message parser deems the command invalid. For example, if the message doesn't terminate with \r\n, the message error:INVALID_TERMINATION is generated.

Syntax Examples¶

/* Read examples */

/* The response 4 shows that the module is in commissioning mesh mode */
>> r:APP_MODE\r\n
>> ok:APP_MODE:4\r\n

/* The fields after the register name represents baudrate = 9600,
   Parity = Even(E) and stop bit = 1 */
>> r:RS485_CONFIG\r\n
>> ok:RS485_CONFIG:9600:E:1\r\n

/* There is no Register with name 'APP' */
>> r:APP\r\n
>> error:UNKNOWN_REGISTER\r\n

/* The command should be terminated with both carriage return '\r'
   and new line '\n' */
>> r:APP_MODE\n
>> error:INCORRECT_TERMINATION\r\n


/* Write examples */

/* The response shows that register is written successfully with value 2 */
>> w:APP_MODE:2\r\n
>> ok:APP_MODE:2\r\n

/* The response shows that register is written with baudrate = 38400,
   Parity = None(N) and stop bit = 2 */
>> w:RS485_CONFIG:38400:N:2\r\n
>> ok:RS485_CONFIG:38400:N:2\r\n

/* There is no register named 'APP' */
>> w:APP\r\n
>> error:UNKNOWN_REGISTER\r\n

Registers¶

The table below lists all registers available in the UART management interface. The first column denotes the name of the register. The "Type" column denotes whether the register is read-only (R), write-only (W), or read-write (R/W).

The final column, "Reset value", denotes the default value of the register. That is, when the module is factory new, or immediately after DEVICE_RESET has been set to 1, the registers values will be set to their reset values. A reset value of - means either the register is write-only, or that it can be different and/or change depending on circumstance. For instance, the reset value of ANTENNA_SELECTOR depends on if the module is an MWA-N2 or MWA-N3 module since only the MWA-N3 has an internal antenna (see Integration page for information about MWA's).

Multi-valued registers like RS485_CONFIG show separated reset values, in the order that they are read & written.

Register name	Type	Reset value
`NETWORK_STATUS`	`R`	`-:-`
`APP_MODE`	`R/W`	`4`
`BOOTLOADER_ENABLED`	`W`	`-`
`FIRMWARE_VERSION`	`R`	`-:-:-`
`RS485_CONFIG`	`R/W`	`0:N:1`
`DEVICE_RESET`	`W`	`-`
`NETWORK_RESET`	`W`	`-`
`SERVER_ADDRESSES`	`R`	`-`
`ANTENNA_SELECTOR`	`R/W`	`-`
`BLUETOOTH_ENABLED`	`R/W`	`0`
`MODBUS_RESCAN`	`R`	`-`

NETWORK_STATUS¶

This register is read-only and contains information about the network status of the device. The register holds two values, of which the first indicates whether the device has received network commissioning data; and the second indicates roughly how stable the connection to the network is. To perform consistently successful network operations (e.g., modifying network baudrate or app mode), it is recommended to do them when the value of NETWORK_STATUS is 1:1 or 1:2.

NOTE: Devices in gateway modes will ALWAYS have the value 1 in the LINK_QUALITY field, due to link quality being measured in relation to the gateway itself.

The subsections below show the two values in the order that they will appear, and the meaning of their possible values.

/* The response when reading `NETWORK_STATUS` will look like this: */
>> ok:NETWORK_STATUS:<COMMISSIONING>:<LINK_QUALITY>\r\n

/* Below is an example with real values: */
>> r:NETWORK_STATUS\r\n
>> ok:NETWORK_STATUS:1:1\r\n

COMMISSIONING¶

Indicates whether any network credentials have been received (i.e. if the device has joined a network).

Value	Meaning
`0`	No commissioning data yet received
`1`	Valid commissioning data has been received

LINK_QUALITY¶

Indicates the stability of any current network connection.

Value	Meaning
`0`	Not connected to a network
`1`	Connected, good link
`2`	Connected, ok link
`3`	Connected, unreliable link

APP_MODE¶

This field is read-write, and determines which application mode the device is in. The module, when factory new, boots into mode 0 (None). This is detected by the application, leading to a switch to the default mode 4 (Commissioning Mesh Mode), causing a restart. In other words, the module will restart once after booting in a factory new state. Writing the value 1 to DEVICE RESET will manually factory reset the device. In other words, writing a 0 or 4 to APP_MODE will put the device in Commissioning Mesh Mode.

The Idle mode will prevent the module from performing any networking, therefore putting it in a sort of sleep. No configuration will be erased when switching to this mode, meaning the module can be put back into secure mode and connect to a previously saved network.

Read more about app modes in the Functional Description which describes the commissioning/decommissioning process.

The table below has a list of all possible modes, along with how many restarts are followed by the switching to a particular mode:

Value	Meaning	Restarts (when written)
`0`	None (will revert to default)	`2`
`1`	Secure Gateway Mode	`1`
`2`	Commissioning Gateway Mode	`1`
`3`	Secure Mesh Mode	`1`
`4`	Commissioning Mesh Mode (default)	`1`
`5`	Idle Mode	`1`

FIRMWARE_VERSION¶

This register is read-only and contains information about the current version the device is running. The module responds with the firmware version in the following format:

>> r:FIRMWARE_VERSION\r\n
>> ok:FIRMWARE_VERSION:3:2:7\r\n

BOOTLOADER_ENABLED¶

This register is write-only and can be used to put the device into bootloader/DFU mode, so that the firmware can be updated.

Value	Meaning	Restarts (when written)
`1`	Enter bootloader/DFU mode	`1`

RS485_CONFIG¶

This register is read-write, and is used to read and configure the following RS485 communication parameters:

Baudrate
Parity
Stop bits

The values are listed in the order in which they are read and written. The example below demonstrates this:

/* Read example */
>> r:RS485_CONFIG\r\n
>> ok:RS485_CONFIG:9600:E:1\r\n

/* Write example */
>> w:RS485_CONFIG:9600:N:1\r\n
>> ok:RS485_CONFIG:9600:N:1\r\n

Baudrate¶

Standard values (in bits/second) 9600 bps, 19200 bps, 38400 bps, 76800 bps have been tested and verified. Larger values, such as 115200 bps, are allowed but have not been tested by LumenRadio.

PARITY¶

Value	Meaning
`N`	No parity
`E`	Even parity

STOP BITS¶

Value	Meaning
`1`	One stop bit
`2`	Two stop bits

DEVICE_RESET¶

This register is write-only and facilitates factory resets of the module. Factory resetting the module means restoring the device to the state it was in when first booting it. Among other things, this action wipes network credentials, RS485 configurations, and resets all register values.

Performing a device reset leads to 2 restarts of the device, the first one after wiping the configuration, which also sets APP_MODE to 0. After restarting the first time, the application will detect that APP_MODE is 0, leading to a switch to the default app mode, 4. This switch leads to the additional restart, after which the device will be in mesh commissioning mode. Read more about this behavior in the APP_MODE section.

Value	Meaning	Restarts (when written)
`1`	Perform a factory reset	`2`

NETWORK_RESET¶

This register is write-only, and when set to 1, wipes any saved network credentials. Configurations other than the network, like the RS485 bus parameters, will remain unaffected.

In practice, this means that devices in Secure Mesh Mode or Commissioning Mesh Mode will leave any joined network. For nodes in any of the gateway app modes, a network reset will clear previously saved network credentials. This can happen if the device was previously in a mesh mode and connected to a network, but was later switched to a gateway.

Value	Meaning	Restarts
`1`	Wipe network credentials	`1` if in Secure Mesh Mode, `0` otherwise

SERVER_ADDRESSES¶

This register is read-only, and contains the address of each detected Modbus device as a list of separated decimal numbers. If there are no detected devices, reading the register will yield no values, like in the example below:

>> r:SERVER_ADDRESSES\r\n
>> ok:SERVER_ADDRESSES:\r\n

This other example shows how it can look with one device detected:

>> r:SERVER_ADDRESSES\r\n
>> ok:SERVER_ADDRESSES:128\r\n

Finally, having multiple detected devices (as possible with pro versions of the module), looks like this:

>> r:SERVER_ADDRESSES\r\n
>> ok:SERVER_ADDRESSES:32:125:126:127:128\r\n

ANTENNA_SELECTOR¶

This register is read-write, and facilitates the selection of either the internal antenna or the external antenna for wireless communication. An antenna switch will always cause one restart.

NOTE: MWA-N2 modules do not have internal antennas, meaning they should not change this field under any circumstances (see Integration page for information about MWA's).

Value	Meaning	Restarts (when changed)
`1`	Internal antenna selected	`1`
`2`	External antenna selected	`1`

BLUETOOTH_ENABLED¶

This register is read-write, and allows Bluetooth Low Energy (BLE) advertising for connections to our app. The device will advertise for 1 minute once the Bluetooth is enabled, and then stop. The W-Modbus app can be downloaded from App store and Play store.

When connecting with our app to a device in secure gateway mode with a firmware version of 3.1.0 or above, the app allows for updating of the firmware, and for an overview of the "network map". It is also possible to see which the currently installed firmware version is.

The network map shows how many devices are present in the network, and how their packets are router through the mesh network. The network map also shows which Modbus addresses have been detected to which W-Modbus device. Through the network map, it is also possible to name W-Modbus devices.

It is possible to connect the app to a non-gateway node, but functionality is limited to only viewing the firmware version and the number of Modbus devices connected.

Value	Meaning
`0`	BLE advertising disabled
`1`	BLE advertising enabled

MODBUS_RESCAN¶

Enables re-scanning for connected Modbus servers on the RS485 bus. After the command is sent, the W-Modbus device can take up to 90 seconds to scan all modbus addresses. During the course of the scan, the contents of the SERVER_ADDRESSES register are invalid.

Value	Meaning
`1`	Enable the rescan

Usage example¶

A simple way to get started is with a USB RS232 interface cable, like the one from FTDI found here. Wire such a cable to the W-Modbus module (see pin assignments) and plug the cable into a computer. Launch a serial terminal with the correct parameters, and start communicating with the module.

See below for a simple pseudo-code example that reads the app mode. The UART interface is assumed to be initialized and configured correctly prior to running the example.

/* Buffer must be large enough to accomodate responses */
uint8_t rx_buffer[BUF_SZ];
uint8_t tx_command[BUF_SZ];

/* Prepare the buffer with command to read the app mode */
memcpy(tx_command, "r:APP_MODE\r\n", BUF_SZ);

/* Send command bytes over UART */
uart_tx(tx_command, BUF_SZ);

/* Receive the response over UART */
uart_rx(rx_command, BUF_SZ);

/* The response from module should be "ok:APP_MODE:4\r\n" in commissioning mesh mode */

/* Check the first and last two bytes to confirm that a complete response is received */
if(rx_command[0] == "o" && rx_command [1] == "k" && rx_command [-1] == "\n" && rx_command [-2] == "\r")
{
    int app_mode = rx_command[-3]; // Extract the APP_MODE value
}