User Tools

Site Tools




WIOpi is a program targeted for the Raspberry Pi and its GPIO. (Model 1, 2, 3, 4 and ZeroW.)
The hardware requirements and support are the same as for RocNetNode.
By running the WIOpi program on the Raspberry Pi, it will behave and process like a WIO on ESP base.

WIOpi runs in context of user pi.

The user pi is default in the groups gpio, i2c and spi, so no need to run WIOpi in super user context.
Note: Type mobile should run in root context to be able to run a high performance motor thread.

$ groups
pi adm dialout cdrom sudo audio video plugdev games users input netdev gpio i2c spi

The following files and directories are extracted:

├── cam
│   └──
├── scripts
│   └── Disco00.led
└── wiopi

The commands to start and stop the Python script can be specified in the wiopi.ini.
Defauls are:

    <var name="startcam" vt="string" defval="nohup python3 cam/ &amp;"/>
    <var name="stopcam" vt="string" defval="killall python3"/>

Supported Boards

  • Raspberry ZeroW 1 and 2
  • Raspberry Pi 1, 2, 3 and 4


Activate I2C, SPI and UART in the raspi-conf utility.

mkdir WIOpi
cd WIOpi
tar xf WIOpi-ARMHF.tar.gz
rm WIOpi-ARMHF.tar.gz

Add a crontab task:

@reboot /home/pi/WIOpi/

The ARMHF build runs also under PiOS 64bit. (ARM64)

Swap Size

The default swap size of 100MB ist for a Zero with 512MB memory not enough.

sudo nano /etc/dphys-swapfile

Change the swap size to 1024:


Restart the service:

sudo /etc/init.d/dphys-swapfile stop
sudo /etc/init.d/dphys-swapfile start

Command Line Options

Option Description
-info set trace level info
-t <filename> trace filename
-server <ip> Rocrail server IP or DNS name ¹
-id <1…255> WIOpi Node ID
-softpwm Use software PWM for servos to enable play sound.

¹ If WIOpi and the Rocrail server are operated on the same Raspberry pi, enter localhost. For autostart, enter the option in


The Pinout and mapping is printed in the console after startup.
It depends on the configuration found in the wiopi.ini.
See for Raspberry Pi Pinout information:
More detailed info:
Or issue in a terminal the pinout command.

Supported Hardware

  • Pi02 (max. 4 = 128 I/O)
  • Pi03 (max. 8 = 128 Servos - address 1-128) 1)
  • Pi06 (Power & Patch)
  • Pi08 (max. 8 = 128 LED. Output address < = 128)
  • ID12 RFID reader on Pi01
  • SSD1306 / SH1106 OLED (max. 2, restricted by the I2C addressing of the SSD1306 / SH1106)
    Note: The SH1106 seems incompatible with the Pi01, I2C Driver, so it must be connected directly to the I2C pins.
  • HT16K33 (max. 2 Clock)
  • BMx280 (max. 2 Environment)
  • GCA214 RailCom reader on Pi01 (PiOS 32bit only because of the none standard baudrate of 250000.)
  • Play sound with "mplayer" (Without prefix forward slash)
  • Mobile soft PWM for controlling a DC Motor, MOSFET or H-Bridge. 2)
  • WS2801 RGB LEDs over SPI (Output address > 128)
    • LEDScript support in case Port Type is set to Macro.
  • 2 Servos on the hardware PWM pins (phys. 32 & 33 - address 129 and 130). 3)
  • Analog inputs: PCF8591

Note: The WIOpi only saves servo positions in case of a shutdown.

Onboard Servos

The two onboard servos have address 129 and 130.
Mobile functions 1 and 2 are mapped to those onboard servo addresses.
Note: The WIOpi only saves servo positions in case of a shutdown.


The Servo outputs, PWM0 and PWM1, can also be used for audio:


The filter is quit simple: (Example is for just one channel, and not tested.)

                 || | 
Servo0 -+---+----|| |----+
        |   |    || |    |   /|
       +-+  |            |  / |
       |1| ---         +---+  |
       |5| --- 33n     |   |  |
       |0|  |          |   |  |
       +-+  |          +---+  |
        |   |            |  \ |
   GND -+---+------------+   \|


LED functions

Both LEDs will flash fast on a show command to identify itself.
Another show command will stop this flashing.

LED1 (green) Description
Off WIOpi does not run, or no GPIO access granted.
Slow flash Normal function.
Fast flash No Rocrail server connection.

LED2 (red) Description
Off Idle communication.
Flash Packet received.


In case both LEDs are flashing to identify itself, it will stop this mode.
Otherwise it sends a query response to the Server.

Signals on Pi02/Pi08/WS2801

Signals Support is also available on the Pi02, in case no Pi08 is connected.

Pi08: 1…128
Pi02: 1…128
WS2801: 129…256 (mapped on 1…128)

ID12LA RFID Reader

The default serial device is /dev/ttyS0, and can be changed in the wiopi.ini:

Raspberry pi Model PiOS 10 PiOS 11
Zero 1 /dev/ttyAMA0
Rpi 1 /dev/ttyAMA0
Zero 2 /dev/ttyS0 /dev/ttyAMA0
Rpi 2…4 /dev/ttyS0

Note: Seems to be PiOS version dependent; Check the system.

Stepper Control

See for turntable setup: WIO Stepper

4 Wire
Function Header GPIO
IN1 (Coil 1) 27 0
GND 9 -
IN2 (Coil 2) 29 5
IN3 (Coil 3) 31 6
IN4 (Coil 4) 35 19
HALL (Calibrate) 37 26


3 Wire
Function Header GPIO Example TB6600
STEP(Clock) 27 0 CLK+
GND 9 - EN-, DIR-, CLK-
DIR 29 5 DIR+
HALL (Calibrate) 37 26



WS2801 Header I/O1 Function
DI 19 MOSI 6 Digital In
CI 23 SCLK 8 Clock In
GND 25 GND 2 Ground

Output settings for LEDScript

Address > 128 or count, ON Parameter, is set to zero.
Options Color, Type Macro.



The Rpi-Zero header mounted on the bottom side. (without factory header)
The Rpi-1/4 header mounted on the top side. (factory default)
Short header on the Rpi-1; No native servo support.

| Rpi0 bottom hdr    |
 |  |
  --       Zero set top
 |  |
 |  |
| WIOpi-01                               |
 |  |                                 || 
 |  |                                 ||
  --       Pi2++ piggy bag            ||
 |  |                                 ||
| Rpi1/4 top hdr                         |


The CAM can be used parallel with WIOpi as documented here:

top - 11:54:34 up 26 min,  2 users,  load average: 1.53, 1.27, 0.85
Tasks:  77 total,   1 running,  76 sleeping,   0 stopped,   0 zombie
%Cpu(s):  7.2 us, 15.4 sy,  0.0 ni, 71.9 id,  0.0 wa,  0.0 hi,  5.5 si,  0.0 st
MiB Mem :    368.4 total,    222.4 free,     73.5 used,     72.5 buff/cache
MiB Swap:      0.0 total,      0.0 free,      0.0 used.    244.2 avail Mem 

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND                                                                              
  527 root      20   0       0      0      0 I   8.1   0.0   0:00.48 kworker/u2:2-brcmf_wq/mmc1:0001:1                                                    
  435 pi        20   0  120260  20208   8232 S   7.8   5.4   1:56.07 python3                                                                              
  301 pi        20   0    9944   2528   2072 S   7.5   0.7   2:00.87 wiopi                                                                                
  526 root      20   0       0      0      0 I   2.9   0.0   0:00.61 kworker/0:1-events                                                                   
  521 pi        20   0   10280   2972   2516 R   1.3   0.8   0:01.73 top                                                                                  

Link to stream:



Function 8 can be used to activate and deactivate the CAM.

I2C Slaves

WIOpi supports up to 4 I2C Slaves.
The reserved I2C device addresses are 0x7C, 0x7D, 0x7E and 0x7F.

To address a pin on a slave, the following parameters are involved:

  • Node ID: The ID of the WIOpi
  • Address: Pin number
  • Port: Slave I2C ID

Supported Rocrail objects:

  • Digital output

Monitor trace DOUT(0x0A) on Pin 5(data[0]) off(data[1]):

opc=0x0A dlc=5 data=05 00 00 00 7C 00 00 00

Ten times a second, the slaves are polled for their input pin state. (If any defined.)

20210105.083513.532 w9999I main     OWire    0187 I2C device found at 0x7C
20210105.083513.542 w9999I main     ODisplay 0392 init SSD1306 device 0x3C geometry=3
20210105.083513.886 w9999I doManage OManager 0101 read reg array slave 0x7C rc=2: opc=0x99 11 66
  • Note 1: The Arduino Nano cannot handle error free I2C speeds above the default 100kHz.

CAN Slaves

The USBtin CAN adapter can be used to include CANGC2 and CANGC6 modules.
The CANGC modules must be programmed as follows:

  • Long events (deselect Short events)
  • The Node Nr. must be set equal to the module its CAN ID
  • The Event Nr. must be set equal to the corresponding port number (1…16)
  • SoD 4711

:!: The programming must be done by the RCAN library in Rocrail; It is not possible to program CANGCx over WIOpi. The same USBtin can be used for this purpose.

Setup examples


Rocrail Addressing

Object Node ID Address Port
Sensor WIOpi Node ID Event Nr. + (Node Nr. * 256) -
Output/Servo WIOpi Node ID Event Nr. Node Nr.

User Pin Definitions

To remap pins for Pi01, Stepper and Mobile, the following child nodes in the wiopi.ini can be used:

<wiopi server="localhost">
  <pindef fn="PWM" nr="12"/>
  <pindef fn="IN1" nr="7"/>

The nr attribute resembles the connector number, not the GPIO.

Name(fn) Description Remark
LED1 Pi01 LED1 output
LED2 Pi01 LED2 output
Button Pi01 Button input
IN1 Stepper IN1 output 3W Clock
IN2 Stepper IN2 output 3W Dir
IN3 Stepper IN3 output 3W Enable
IN4 Stepper IN4 output
CAL Stepper calibration input
PWM Mobile PWM output
FWD Mobile forwards relay pulse output
REV Mobile reverse relay pulse output
LIGHTS1 Mobile lights Cab 1 output
LIGHTS2 Mobile lights Cab 2 output

Auto Server Connect

WIOpi use the R2RNet service to detect the Rocrail server in the LAN.
This service must be activated in the server settings.

If Auto Server Connect doesn't work (f.e. the router doesn't support UDP Multicast) the Rocrail Server IP or Name can be added to the wiopi.ini:

<wiopi server="insert the server ip here" nid="99" nodename="WIOpi">

WIOpi should be stopped before editing this file:

sudo killall wiopi

Info Level

You can edit the with sudo nano
Add -info behind ./wiopi for information:

cd /home/pi/WIOpi
sudo ./wiopi -info

This should only be done for testing because of cpu utilization

Mobile Dual Motor

Locomotives with dual motors require dual H-Bridge support.
Set the "dualmotor" option to "true" in the wiopi.ini to enable this.
The second H-Bridge connects to the I/O2 connector on pin 4, 5 and 6.
The WIO-Drive, without ESP, can be used as second H-Bridge. Mount only those parts needed for controlling the H-Bridge. Do not place the rectifier, but wire it.

I/O2 H-Bridge Rpi Conn WIODrive
2 GND 25 IBB1-3
4 IN2 29 IBB1-2
5 IN1 31 IBB1-1
6 ENA 35 ESC1-3
The WIOpi only saves servo positions in case of a shutdown.
WIOpi must be started with sudo to generate a good quality PWM.
WIOpi must be started with sudo to be able to use the PWM outputs.
wio/wiopi-en.txt · Last modified: 2024/04/13 16:28 by babbel