IOU04 Detailed Description

Serial Interfaces

The IOU04 has two identical serial interfaces, labelled COM1 and COM2.

Features

  • RS232 or RS485-full-duplex or RS485-half-duplex
  • Virtual tty support using RFC2217
  • Appears as a standard tty device on Linux hosts
  • Baudrates up to 460800 Baud
  • Galvanic Isolation between the COM port and other ports

Connection

COM port connector on IOU04:

COM Port Connector

Pin functionality as viewed from IOU04:

Pin Symbol Description
1 RS485_TX+ RS485 positive transmit line
2 RS232_TXD RS232 transmit line
3 RS232_RXD RS232 receive line
4 RS485_RX+ RS485 positive receive line
5 GND Ground (isolated from other interfaces)
6 RS485_TX- RS485 negative transmit line
7 RS232_CTS RS232 Clear to Send
8 RS232_RTS RS232 Request to Send
9 RS485_RX- RS485 negative receive line

Typical Connection Examples

COM Port Connector

Important Notes:

Whether to use RS232 or RS485 is solely defined by hardware connection. It is not defined by software configuration. However, hardware flowcontrol and half/full-duplex operation must be configured in software!

For RS485/RS422 half-duplex operation, you must externally connect the COM ports Rx pins with the corresponding Tx pin

In RS485/RS422 mode, please add termination resistors to the end of the line. The termination must be 120R at each end of the cable.

Operating Principle of IP Based COM-Port

COM ports on the IOU04 are exposed to the network as a ttynvt (network virtual terminal) service. For each COM port, a TCP-Server, implementing the RFC2217 protocol is active on the IOU04, each TCP-Server uses a dedicated TCP port.

RFC2217 extends the telnet protocol by adding COM port configuration commands, flow control and more. In addition to RFC2217 standard, we have added a proprietary extension for IOU04 to control half duplex operation. (See TNS_CTL_ENABLE_RS485 and TNS_CTL_DISABLE_RS485 in the telnet header file)

To access the COM ports from the host, you can

  • Use the ttynvt program to create a virtual /dev/tty device for each COM port.
  • Use pyserial’s RFC2217 support

Using ttynvt

An instance of ttynvt must be started for each virtual RFC2217 COM port. ttynvt creates a device entry in /dev, e.g. /dev/ttyS101-IOU04-USB-EXT-1-com1. Your application can then use this device as any other tty device in the system.

If you are using a Linux Image from Ci4Rail, ttynvt instances are automatically started for each ttynvt COM port in the network via ttynvt-runner. ttynvt-runner is started as a systemd service.

Using Half Duplex Mode with ttynvt

Half duplex mode must be used with the RS485/RS422 signals on the connector. In half duplex mode, two or more participants share the Rx/Tx lines. Only one participant is allowed to drive the Tx data.

To enable half duplex mode, the application must call iotcl TIOCSRS485 on the tty device provided by ttynvt. In python, this can be done like this:

import serial
import serial.rs485

ser = serial.Serial(
                port="/dev/S101-IOU04-USB-EXT-1-com1",
                baudrate = 115200,
                parity=serial.PARITY_NONE,
                stopbits=serial.STOPBITS_ONE,
                bytesize=serial.EIGHTBITS,
                timeout=1,
                rtscts = False
            )

# Set half duplex operation
ser.rs485_mode = serial.rs485.RS485Settings()

ser.write(bytes("Hello World", "utf8"))

data = ser.read(10)
print("data: {}".format(data))

NOTE: In half duplex mode, the data that is sent to the line is NOT echoed back to the application, because the receiver is disabled while sending.

Using pyserial with RFC2217

pyserial provides a way to communicate directly with RFC2217 compliant servers, this way, ttynvt is not required.

The following example opens COM1 of the IOU04 with device id S101-IOU04-USB-EXT-1 (port 10000 is the port for COM1), sets the baudrate to 19200 and sends and receives some characters:

import serial

ser = serial.serial_for_url("rfc2217://S101-IOU04-USB-EXT-1.local:10000?ign_set_control")
ser.baudrate = 19200

ser.write(bytes("Hello World", "utf8"))

data = ser.read(10)
print("data: {}".format(data))

NOTE pyserial with RFC2217 does not support the proprietary extension to set the COM port into half duplex mode. Therefore half-duplex mode is not supported.

Considerations when running with Handshaking enabled

The COM port supports hardware (CTS/RTS) and software (XON/XOFF) handshaking for flow control. A receiver may stop the sender by de-asserting CTS or sending an XOFF character.

However, be aware about the following behaviour: When the IOU04 is the sender and the connected receiver forces the transmission to stop, the IOU04 may hang until the transmission is re-enabled again by the receiver. Even if you stop the transmitting process, the firmware will not accept any new connection request until its transmit buffer gets empty.

If you run into such a situation and the receiver will never re-enable the transmission (for example because you have selected hardware handshake but you haven’t connected CTS), you must restart the IOU04, for example using the io4edge-cli.

CANBus Interface

The IOU04 has one CANBus interfaces, labelled CAN.

Features

  • ISO 11898 CANBus Interface, up to 1MBit/s
  • Usable for direct I/O or as data logger with multiple data streams.
  • SocketCAN Support
  • Standard and Extended Frame Support
  • RTR Frame Support
  • Fixed Listen Only Mode
  • One Acceptance Mask/Filter

Connection

Connection is done via 9-pin DSub plug:

Pin Symbol Description
1 - Not connected
2 CAN_L CAN Signal (dominant low)
3 GND_ISO CAN Ground
4 - Not connected
5 SHIELD Shield
6 GND_ISO CAN Ground
7 CAN_H CAN Signal (dominant high)
8 - Not connected
9 - Not connected

Using the io4edge API to access CAN Function

If you haven’t installed yet the io4edge client software, install it now as described here.

Want to have a quick look to the examples? See our Github repository

Connect to the CAN Function

To access the CAN Function, create a Client and save it to the variable c. Pass as address either a service address or an ip address with port. Example:

  • As a service address: S101-IOU04-USB-EXT-1-can
  • As a IP/Port: e.g. 192.168.201.1:10002

We need this client variable for all further access methods.

import (
  "fmt"
  "os"
  "time"
  "github.com/ci4rail/io4edge-client-go/canl2"
  fspb "github.com/ci4rail/io4edge_api/canL2/go/canL2/v1alpha1"
)

func main() {
  const timeout = 0 // use default timeout

  c, err := canl2.NewClientFromUniversalAddress("S101-IOU04-USB-EXT-1-can", timeout)
  if err != nil {
    log.Fatalf("Failed to create canl2 client: %v\n", err)
  }
}

Bus Configuration

There are two ways to configure the CAN function:

  • Using a persistent parameter that is stored in the flash of the IOU04, as described here.
  • Temporarily, via the io4edge CANL2 API, as shown below
Temporary Bus Configuration

Bus Configuration can be set via UploadConfiguration. All settings remain active until you change it again or restart the device.

When the device is restarted, it will apply the persistent configuration stored in flash, or - if no persistent configuration is available - will keep the CAN controller disabled.

  err = c.UploadConfiguration(
    canl2.WithBitRate(125000),
    canl2.WithSamplePoint(0.625),
    canl2.WithSJW(1),
    canl2.WithListenOnly(true),
  )

Receiving CAN Data

To receive data from the CANbus, the API provides functions to start a Stream.

Without any parameters, the stream receives all CAN frames:

// start stream
err = c.StartStream()

Missing parameters to ´StartStream` will take default values:

  • Filter off (let all CAN frames pass through)
  • Maximum samples per bucket: 25
  • Buffered Samples: 50
  • Keep Alive Interval: 1000ms
  • Low Latency Mode: off

In the stream the firmware generates Buckets, where each Bucket contains a number of Samples. Each sample contains:

  • A timestamp of the sample
  • The CAN frame (may be missing in case of bus state changes or error events)
  • The CAN Bus state (Ok, error passive or bus off)
  • Error events (currently: receive buffer overruns)

For efficiency, multiple samples are gathered are sent as one Bucket to the host. To read samples from the stream:

  for {
    // read next bucket from stream
    sd, err := c.ReadStream(time.Second * 5)

    if err != nil {
      log.Printf("ReadStreamData failed: %v\n", err)
    } else {
      samples := sd.FSData.Samples
      fmt.Printf("got stream data with %d samples\n", len(samples))

      for _, s := range samples {
        fmt.Printf("  %s\n", dumpSample(s))
      }
    }
  }

func dumpSample(sample *fspb.Sample) string {
  var s string

  s = fmt.Sprintf("@%010d us: ", sample.Timestamp)
  if sample.IsDataFrame {
    f := sample.Frame
    s += "ID:"
    if f.ExtendedFrameFormat {
      s += fmt.Sprintf("%08x", f.MessageId)
    } else {
      s += fmt.Sprintf("%03x", f.MessageId)
    }
    if f.RemoteFrame {
      s += " R"
    }
    s += " DATA:"
    for _, b := range f.Data {
      s += fmt.Sprintf("%02x ", b)
    }
    s += " "
  }
  s += "ERROR:" + sample.Error.String()
  s += " STATE:" + sample.ControllerState.String()

  return s
}

NOTE: At the moment, timestamps are expressed in micro seconds relative to the start of the IOU04. Future client libraries will map the time to the host’s time domain

Controlling the Stream

It is possible to fine-tune the stream behavior to the application needs:

Configure a keep alive interval, then you get a bucket latest after the configured interval, regardless whether the bucket is full or not:

  // configure stream to send the bucket at least once a second
  err = c.StartStream(
    canl2.WithFBStreamOption(functionblock.WithKeepaliveInterval(1000)),
  )

Configure the number of samples per bucket. By default, a bucket contains max. 25 samples. This means, the bucket is sent when at least 25 samples are available. If number of buckets per sample is changed, the number of buffered samples for this stream in the device must be changed accordingly. As a rule of thumb, Buffered Samples should be at least two times the number of samples in the bucket. Select a higher number if your reception process is slow to avoid buffer overruns.

If you want low latency on the received data, you can enable the “low latency” mode. In this mode, samples are sent as soon as possible after they have been received. This means that the buckets contain 1..<samples-per-bucket> samples.

  // configure stream to send the bucket at least once a second
  // configure the maximum samples per bucket to 25
  // configure low latency mode
  // configure the buffered samples to 200
  err = c.StartStream(
      canl2.WithFBStreamOption(functionblock.WithKeepaliveInterval(1000)),
      canl2.WithFBStreamOption(functionblock.WithBucketSamples(25)),
      canl2.WithFBStreamOption(functionblock.WithLowLatencyMode(true))
      canl2.WithFBStreamOption(functionblock.WithBufferedSamples(200)),
  )

If you don’t want to receive all CAN identifiers, you can specify an acceptance code and mask that is applied to each received frame. The filter algorithm is pass_filter = (code & mask) == (received_frame_id & mask). The same filter is applied to extended frames and standard frames.

  // apply a filter. Frames with an identifier of 0x1xx pass the filter, other frames are filtered out
  code := 0x100
  mask := 0x700
  err = c.StartStream(
    canl2.WithFilter(code, mask),
  )
Error Indications and Bus State

The samples in the stream contain also error events and the current bus state.

Error events can be:

  • ErrorEvent_CAN_NO_ERROR - no event
  • ErrorEvent_CAN_RX_QUEUE_FULL - either the CAN controller dropped a frame or the stream buffer was full

Each sample contains also the bus state. When the bus state changes, a sample without a CAN frame may be generated. Furthermore, client method GetCtrlState may be used to query the current status.

Bus States can be:

  • ControllerState_CAN_OK - CAN controller is “Error Active”
  • ControllerState_CAN_ERROR_PASSIVE - CAN controller is “Error Passive”
  • ControllerState_CAN_BUS_OFF - CAN controller is bus off

Bus Off Handling

When the CAN controller detects serious communication problems, it enters “Bus off” state. In this state, the CAN controller cannot communicate anymore with the bus.

When bus off state is entered, The firmware waits 3 seconds and then resets the CAN controller.

Multiple Clients

It is possible to have multiple clients active at the same time. For example: One client receiving a stream with a specific filter and a another client receiving a stream with a different filter.

Using SocketCAN

In Linux, SocketCAN is the default framework to access the CANBus from applications.

The IOU04 can be integrated into SocketCAN using the socketcan-io4edge gateway:

IOU04 product view

NOTE: When using SocketCAN, you must configure the CAN Controller persistently as shown here IOU04, as described here.

In Ci4Rail Linux Images, the socketcan-io4edge gateway is started automatically by socketcan-io4edge-runner which detects available io4edge devices with CAN support and start an instance of the socketcan-io4edge gateway, if the corresponding virtual can instance exists. For an example, see here.