MIO03 Quick-Start-Guide

Establishing Host Connection and Power

ModuSio devices can be connected to the Network via Ethernet or Wifi. Please select the tab for your preferred option:

Ethernet: Network and Power Connection

When the MIO03 is connected to the host via Ethernet, the power should be provided via Power-Over-Ethernet.

ModuSio devices are Class 2 (3,84–6,49 W) PoE powered devices. Connect the ModuSio Device to a PoE source that can supply class 2 devices. ModuSios expect the PoE power as phantom power, i.e. using the Ethernet Tx and Rx pins.

PoE connection

The green LED on the MIO03 is turned on to indicate power is ok and firmware is up and running.

Initial Device Configuration

For initial configuration, connect the SERVICE interface to a computer via USB cable and start a terminal program. See Instructions for details.

Press Enter in the Terminal program, and you should see the config prompt:

config>

Configure Device ID

To identify the device in the network, configure a device ID. This ID is used as the network hostname and as a prefix to identify the services provided by the device.

Each device in the network shall have a unique name. The name shall consist only of alphanumeric characters, - and _. Avoid blanks and special characters.

config> device-id MIO03-1
Setting device-id to 'MIO03-1'
A 'reboot' is required to activate the new setting!

Select Ethernet as Host Interface

Configure the device for Ethernet operation. The device is configured for Ethernet when it is NOT configured for Wifi. So we clear Wifi settings:

config> wifi-ssid ""
Delete wifi-ssid

You can ignore the message: Can't set wifi-ssid: ESP_ERR_NVS_NOT_FOUND. This is normal if wifi has not been configured before.

Configure IP Address

The ModuSio needs an IP address in the network. It can be configured to use a static IP address or to use dynamic IP address, provided by a DHCP server.

Setup for DHCP

To obtain the devices IP address from a DHCP server, clear any static IP address setting:

config> static-ip ""
Delete static-ip

You can ignore the message: Can't set static-ip: ESP_ERR_NVS_NOT_FOUND. This is normal if no static IP has not been configured before.

Activate the changes:

config> reboot
Setup Static IP

To use a static IP address, configure the IP-Address, Gateway and Network Mask using the static-ip command. The three parameters have to be specified as a single string, separated by colons (:), <ip>:<netmask>:<gateway>.

config> static-ip 192.168.1.56:255.255.255.0:192.168.1.1
Setting static-ip to '192.168.1.56:255.255.255.0:192.168.1.1'
A 'reboot' is required to activate the new setting!

Activate the changes:

config> reboot
Connection Test

Now try to test the connection using ping from a computer in the same network as your device. Use the device ID of your device and append .local.

$ ping MIO03-1.local
PING MIO03-1.local (192.168.1.56) 56(84) bytes of data.
64 bytes from 192.168.1.56: icmp_seq=1 ttl=255 time=57.1 ms
64 bytes from 192.168.1.56: icmp_seq=2 ttl=255 time=76.4 ms

Wifi: Network and Power Connection

When using Wifi, supply the ModuSio by a power supply, capable of delivering 12V..24VDC, 5W. Use contacts 5+6 and 7+8 to supply the power. Polarity doesn’t matter.

Wifi connection

The green LED on the MIO03 is turned on to indicate power is ok and firmware is up and running.

Initial Device Configuration

For initial configuration, connect the SERVICE interface to a computer via USB cable and start a terminal program. See Instructions for details.

Press Enter in the Terminal program, and you should see the config prompt:

config>

Configure Device ID

To identify the device in the network, configure a device ID. This ID is used as the network hostname and as a prefix to identify the services provided by the device.

Each device in the network shall have a unique name. The name shall consist only of alphanumeric characters, - and _. Avoid blanks and special characters.

config> device-id MIO03-1
Setting device-id to 'MIO03-1'
A 'reboot' is required to activate the new setting!

Select Wifi as Host Interface

Configure the device for Wifi operation. You need the Access Point’s Name (SSID) and a password.

config> wifi-ssid <my-access-point-name>
config> wifi-pw <my-secret-password>

WARNING: It is not possible to connect to Access Points that don’t require a password.

Configure IP Address

The ModuSio needs an IP address in the network. It can be configured to use a static IP address or to use dynamic IP address, provided by a DHCP server.

Setup for DHCP

To obtain the devices IP address from a DHCP server, clear any static IP address setting:

config> static-ip ""
Delete static-ip

You can ignore the message: Can't set static-ip: ESP_ERR_NVS_NOT_FOUND. This is normal if no static IP has not been configured before.

Activate the changes:

config> reboot
Setup Static IP

To use a static IP address, configure the IP-Address, Gateway and Network Mask using the static-ip command. The three parameters have to be specified as a single string, separated by colons (:), <ip>:<netmask>:<gateway>.

config> static-ip 192.168.1.56:255.255.255.0:192.168.1.1
Setting static-ip to '192.168.1.56:255.255.255.0:192.168.1.1'
A 'reboot' is required to activate the new setting!

Activate the changes:

config> reboot
Connection Test

Now try to test the connection using ping from a computer in the same network as your device. Use the device ID of your device and append .local.

$ ping MIO03-1.local
PING MIO03-1.local (192.168.1.56) 56(84) bytes of data.
64 bytes from 192.168.1.56: icmp_seq=1 ttl=255 time=57.1 ms
64 bytes from 192.168.1.56: icmp_seq=2 ttl=255 time=76.4 ms

Troubleshooting Wifi Connection

In case Wifi connection doesn’t work, enter reboot in the SERVICE console and check the log messages.

Look for messages beginning with wifi: and io4edge_net:. In case of success, you see something like

...
I (848) wifi:connected with my-access-point-name, aid = 1, channel 6, BW20, bssid = ...
...
I (2573) io4edge_net: Got IP Address
I (2573) io4edge_net: ~~~~~~~~~~~
I (2573) io4edge_net: ETHIP:192.168.1.56
I (2574) io4edge_net: ETHMASK:255.255.255.0
I (2574) io4edge_net: ETHGW:192.168.1.1
I (2574) io4edge_net: ~~~~~~~~~~~
...

If connection establishment isn’t successful, you see periodically something like this:

I (6954) io4edge_wifi: Disconnected, reconnect

You can also scan for available access points. To enable wifi scanning, just set a dummy access point name:

config> wifi-ssid foo
config> reboot
...
config> wifi-scan
Total APs scanned = 2
                                    SSID RSSI Channel
                                  slinky -47   6
                            OfficeRouter -53   1

In this quick-start guide we will run demo programs that dump the frames on the MVB and CAN bus MIO03 to the console.

Prerequisites

Hardware

  • A target machine running Linux that is in the same network as your MIO03
  • A development PC (Windows or Linux), connected via Network to the target machine

For MVB Demo:

  • MVB bus with at least a Master and a Slave

For CAN Demo:

  • CANbus with at least two CAN devices
  • Cable to connect the CAN device with the MIO03

Tools on Development PC

The examples are written in programming language Go, we download the go sources and compile them. Therefore we need some tools on your development PC:

Get Demo Software

Clone the repository containing the examples to a folder of your choise (here myworkdir)

c:
cd \myworkdir
git clone https://github.com/ci4rail/io4edge-client-go.git
cd io4edge-client-go
cd ~/myworkdir
git clone https://github.com/ci4rail/io4edge-client-go.git
cd io4edge-client-go

MVB Demo with Simulated Frames

The MVB loop demo will use the MIO03 internal MVB frame generator to simulate frames on the MVB, you don’t need to connect anything to the MVB connectors. The generated frames do not leave the MIO03. They are internally looped back in the MIO03.

The demo then dumps the simulated received frames to the console.

Demo Software

Compile Demo

The demo must be compiled for the architecture of your target machine. Typical targets are:

  • modern x86 PCs: Architecture = amd64
  • RaspberryPi (32 Bit): arm
  • ModuCop: arm64

In the following examples, we use arm.

Run this in a powershell console

cd examples\mvbSniffer\stream
$Env:GOOS = "linux"
$Env:GOARCH = "arm"
go build
cd examples/mvbSniffer/stream
GOOS=linux GOARCH=arm go build

This produces the binary file stream in the current folder.

Copy Demo to target machine

Transfer the compiled binary. Replace <target-ip> with the IP address of your target machine.

scp stream <target-ip>:/~

Running the Demo

Login into your target machine over SSH:

ssh <target-ip>

Once logged in into the target machine’s Shell, run the demo.

./stream -gen MIO03-1-mvbSniffer

You should see an output like this:

Started stream
dt=0 addr=000123, kProcessData32Bit, data=01 02 03 04
dt=288 addr=000456, kProcessData16Bit, data=aa bb
dt=877 addr=000123, kProcessData32Bit, data=01 02 03 04
dt=288 addr=000456, kProcessData16Bit, data=aa bb
dt=877 addr=000123, kProcessData32Bit, data=01 02 03 04
dt=288 addr=000456, kProcessData16Bit, data=aa bb
dt=877 addr=000123, kProcessData32Bit, data=01 02 03 04
dt=288 addr=000456, kProcessData16Bit, data=aa bb
...

Receive from a Real MVB

To receive frames from the MVB, connect the MIO03 to a real MVB. The MVB bus is connected to the MIO03 via the two connectors labelled MVB1 and MVB2.

Connecting

MVB may be EMD or ESD. Depending on the position of the MIO03 in the bus, connect it like in the following drawing:

Connection for Binary I/O Demo

Demo Software

Run the same demo software as in the previous section, but don’t specify the -gen flag.

./stream MIO03-1-mvbSniffer

Then the tool should dump all telegrams on the bus to the console.

CAN Demo using the Io4Edge API

In this demo, we’ll demonstrate how to receive data from a CAN bus and print it to the console. This demo directly accesses the MIO03 CAN interface via the Io4Edge API.

Bus Configuration

Bus Configuration must be set once to tell the MIO03 about the CAN parameters. This configuration is saved persistently in the device. You only need to perform this configuration step once, it survives reboots and power cycles.

In this example, we assume your

  • Bitrate is 125 kBit
  • Sampling Point is 62.5%
  • Synchronization Jump Width is 1
  • Listen only mode is on (because the MIO03 can’t send)

Configure the device. You specify a string that has the form bitrate:sampling-point/1000:sjw:listen-only

Warning Always set the listen-only flag to 1 on the MIO03. Otherwise the device may try to send ACKs on the bus and this might result in incorrect behavior also on the receiver side.

On your target machine, run:

io4edge-cli -d MIO03-1 set-parameter can-config 125000:625:1:1

Alternatively, you can define the CAN configuration via the SERVICE interface and the config menu:

config> can-config 125000:625:1:0
config> reboot

Connecting

CAN Connection

Connect CAN_L, CAN_H and GND_ISO to the CAN bus. Be sure to have correct termination of 120R at each end of the line.

Demo Software

Compile Demo

The demo must be compiled for the architecture of your target machine. Typical targets are:

  • modern x86 PCs: Architecture = amd64
  • RaspberryPi (32 Bit): arm
  • ModuCop: arm64

In the following examples, we use arm.

Run this in a powershell console

cd examples\canL2\streamDump
$Env:GOOS = "linux"
$Env:GOARCH = "arm"
go build
cd examples/canL2/streamDump
GOOS=linux GOARCH=arm go build

This produces the binary file streamDump in the current folder.

Copy Demo to target machine

Transfer the compiled binary. Replace <target-ip> with the IP address of your target machine.

scp streamDump <target-ip>:/~

Running the Demo

Login into your target machine over SSH:

ssh <target-ip>

Once logged in into the target machine’s Shell, run the demo.

./streamDump MIO03-1-can

Now you should see all frames that are sent on the CAN bus. Example:

Started stream
got stream data with 3 samples
  @56036918665 us: ID:7ff DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
  @56037270984 us: ID:123 DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
  @56037462740 us: ID:456 DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
got stream data with 3 samples
  @56038232385 us: ID:222 DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
  @56038422757 us: ID:334 DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
  @56038632969 us: ID:555 DATA:22 33 44  ERROR:CAN_NO_ERROR STATE:CAN_OK
...

SocketCAN Demo

In this demo, we’ll demonstrate how to receive data from a CAN bus and print it to the console. This demo is using the Linux SocketCAN framework.

WARNING This documentation assumes that ModuCop is your target. Users of other Linux machines: Please install our Open Source socketcan-io4edge solution on your target.

First, configure the bus parameters as described here.

Create a socketCAN instance

To access the MIO03 via socketCAN, we create a virtual socketCAN network that matches the service name of your MIO03 CAN Interface.

The virtual socket CAN network must be named according to MIO03 CAN Interface service name. E.g. if the service name is MYDEV-can, the virtual socketCAN device must be named vcanMYDEV (without -can). Because network interface names can have only max. 15 characters, but service names can be longer, there is a rule to map longer service names to socketCAN device names:

vcan<first-4-chars-of-service-name>xx<last-5-chars-of-service-name>

Examples:

  • Service Name S101-IOU04-USB-EXT-1-can -> vcan name vcanS101xxEXT-1
  • Service Name 123456789012-can -> vcan name vcan1234xx89012
  • Service Name MIO03-1-can -> vcan name vcanMIO03-1

Now, create a virtual socketCAN network. On your target machine, execute:

ip link add dev vcanMIO03-1 type vcan
ip link set up vcanMIO03-1

Function Test

Using the candump tool (part of can-utils package), you should see all frames that are sent on the CAN bus. Example (would dump also error information from CANbus):

./candump vcanMIO03-1 vcanMIO03-1,1FFFFFFF:1FFFFFFF,#FFFFFFFF -e
  vcanMIO03-1  6B6   [5]  37 67 2F 0F F2
  vcanMIO03-1  24A   [6]  B1 39 8A 3A A5 77
  vcanMIO03-1  57C   [5]  01 B2 9F 37 22
  vcanMIO03-1  665   [8]  1C C2 60 0A 8E E3 85 42
  vcanMIO03-1  18B   [5]  B0 E5 E4 2E 24
  vcanMIO03-1  0D0   [8]  64 49 45 71 6B B2 6E 09
  vcanMIO03-1  146   [7]  2E A6 CF 44 1A E9 2A
  vcanMIO03-1  508   [0]
  vcanMIO03-1  726   [8]  B0 B5 2E 62 70 89 78 4F
  vcanMIO03-1  454   [2]  15 01