Serial IO - FreeWaveTechnologies/ZumIQ GitHub Wiki

Introduction

Most of the information you need to access the serial ports in your applications can be found in the User Manual. This document goes into more depth about a few important considerations.

Handler Settings - Summary

Options for the COM1 and COM2 Handler setting are summarized in Table 1 below.

Setting	Description
Modbus RTU	Allows for Modbus RTU command into the ZumLink
TerminalServer	Connects port 5041 (COM1) or 5042 (COM2) to the serial port
Cli	Puts the FreeWave Shell command-line interface on the serial port
ModbusPassthru	Passes commands through the ZumLink to Modbus serial devices
Trace	Puts the CLI on the port with trace capability (useful for debugging)
Setup	Sets the port and then frees it for direct access (RS-232/422 only)
off	Port will not be configured or opened (RS-232 only)

Handler Settings - Detail

ModbusRTU

This allows the ZumLink to receive, process, and respond to Modbus RTU commands. The ZumLink's Modbus registers are listed in the User's manual. They can also be listed using the CLI command modbus.modbusLayout.

TerminalServer

This connects port 5041 (COM1) or 5042 (COM2) to the serial port. In RS-232 mode, applications can connect to the port through either direct connection (see Setup below) or through the TCP ports. In RS-485, applications can connect to the serial port through the TCP ports only.

Cli

This puts the FreeWave Shell CLI on the port. This is the same command-line interface that the user accesses through the USB/serial connection or through an ssh connection.

ModbusPassthru

In ModbusPassthru mode, the ZumLink takes commands that come in through Modbus RTU (the other COM port), Modbus TCP (port 502) or Modbus RTU over TCP (port) 5021.

If a command is intended for a Modbus device ID other than the ZumLink, it passes the command to the Modbus device and returns the response to the sender. If a command is intended for the ZumLink (its default Modbus Device ID is 1), it processes the command itself and returns a response to the sender.

Trace

Similar to Cli, but it also puts a trace on the serial port.

Setup

This sets up the serial port and then frees the port for direct access.

Direct access only works for RS-232 and RS-422, not for RS-485. Instead, for programmatic serial communications in RS-485 mode, set Handler to TerminalServer, and access the serial ports through the IP stack, using ports 5041 (COM1) and 5042 (COM2).

off

Closes the serial port. With Handler set to off, an application cannot configure or open the port for direct access. However, this only applies to RS-232 direct access. Behavior for other modes of access is undefined and should not be assumed to be deterministic or predictable.

Direct Access to the Serial Ports

In RS-232, configure the serial port with the following settings. Settings not shown are at the user's discretion. Substitute com1 for com2 if configuring the COM2 port.

com1.mode=RS232
com1.handler=Setup
...
duplex=Full

COM1 can be accessed as /dev/ttyO5, and COM2 can be accessed as /dev/ttyO1. That's an "oh" as in "output", not a "zero".

NOTE: Starting with firmware version 1.1.2.2, those assignments have changed. COM1 can be accessed as /dev/ttyO1, and COM2 can be accessed as /dev/ttyO2. That's an "oh" as in "output", not a "zero".

The following simple Python script demonstrates how to directly access the serial port. Two different serial libraries exist for Python, serial and pyserial. The pyserial library is preferred, and should be installed using pip before running this program.

import serial

ser = serial.Serial('/dev/ttyO5', 9600) # open serial port
message = b'Hello - type 10 characters\r\n'
ser.write(message)          # write message to serial port
response = ser.read(10)     # read response from serial port
ser.write(b'\r\n')
ser.close()                 # never leave a serial port dangling open
print(response)

Accessing the Serial Ports Using the IP Stack

In RS-485 mode, configure the serial port with the following settings. Settings not shown are at the user's discretion. Substitute com1 for com2 if configuring the COM2 port.

RS-232 and RS-422 can use either direct access or IP access. For RS-485, IP access is the only option.

com1.mode=RS485            # RS232 for RS-232, RS485 for RS-422 or RS-485
com1.handler=TerminalServer
...
duplex=Half                # Full for RS-232 or RS-422, Half for RS-485
com1.terminalServerPort=5041

COM1 can be accessed as 5041, and COM2 can be accessed as 5042. Note that these are default settings, and can also be changed at the user's discretion.

The following simple Python script demonstrates how to connect to the serial port through the IP stack.

import socket

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# s.connect(('127.0.0.1', 5041)) # use 5041 for com1, 5042 for com2
s.connect(('localhost', 5041)) # use 5041 for com1, 5042 for com2

message = 'Hello - type 10 characters\r\n'
s.send(message.encode())    # write message to serial port

response = ''
while True:
    response += s.recv(16)  # read response from serial port
    if len(response) >= 10:
        break

s.send(b'\r\n')
s.close()                   # don't leave the socket hanging
print(response)

RS-422

The ZumLink also supports RS-422 communication. See the section Serial Pinout Assignments in the User Manual.

To set up RS-422 communications on the ZumLink, configure the serial port with the following settings. Settings not shown are at the user's discretion. Substitute com1 for com2 if configuring the COM2 port.

com1.mode=RS485
com1.handler=Setup
...
duplex=Full

In RS-422 mode, the ports can be accessed either directly or using the IP stack.

Investigation in progress: Since RS-422 and RS-485 are both differential-voltage signals, there are reports that it may be possible to spoof the ZumLink into using direct access for RS-485 by connecting the RX+ and TX+ signals, and the RX- and TX- signals at the ZumLink. DISCLAIMER: This page is still under construction, and this connection has not been thoroughly tested and vetted yet. However, it works on another FreeWave product. This disclaimer will be removed after the connection has been vetted.

Modbus RTU, Modbus TCP, Modbus RTU over TCP

to be determined

Examples

Example 1: Serial port connected to a terminal

Follow these steps to test the code examples above.

Connect the ZumLink to a PC using the proper interface cable (RS-232, RS-422, or RS-485). Set the proper settings in the COM1 or COM2 configuration menu.

Start a terminal emulator on the PC, such as Hyperterm, Tera Term, PuTTy, or MobaXterm. Open a serial connection in the terminal emulator program, selecting PC's COM port corresponding to the COM1 or COM2 connection on the ZumLink.

(Take care not to select the PC's COM port corresponding to the USB/serial connection on the ZumLink.)

In a separate window, with a USB/serial or ssh connection to the ZumLink, execute the Python script on the ZumLink. For example, if you have saved the program as serialtest.py, then execute the command:

python serialtest.py

on the ZumLink.

You should see the text "hello" appear in the terminal window. If you type something in the terminal window, you should see the text appear in the window from which you executed the script.

Example 2: Terminal Server Relay

to be determined

Example 3: Modbus RTU

to be determined

Example 4: Modbus TCP

to be determined

Example 5: Modbus RTU over TCP

to be determined