Wiznet makers

Summary

SAINT.OS (in the input-inc/saintos repository) is a ROS2-based control system for a distributed mobile robot, with a Raspberry Pi “server” coordinating multiple peripheral nodes (head, arms, tracks). WIZnet’s W5500 is used on RP2040-class microcontroller nodes to provide wired Ethernet, enabling a custom micro-ROS transport over UDP with DHCP and socket handling via WIZnet ioLibrary—so the internal robot network can stay deterministic and isolated from the external “operator/admin” network.

What the Project Does

SAINT.OS is positioned as an operating system for a track-based mobile robot with multiple articulated subsystems. The repo describes a distributed architecture: a central server (Raspberry Pi 4/5) coordinates ROS2 and bridges external control inputs (WebSocket, face tracking/LiveLink, RC controllers), while peripheral “nodes” handle specific mechanisms such as head motion, arms, and tracks.

A key design choice is that microcontroller nodes are intended to run micro-ROS and communicate to the server over UDP, with the micro-ROS agent embedded on the server side to bridge Micro XRCE-DDS to the full ROS2 DDS network. This creates a clean separation between:

• high-level decision/control logic and UI on the server, and
• low-level deterministic I/O on distributed nodes.

Where WIZnet Fits

SAINT.OS explicitly treats wired Ethernet as the required internal network for nodes, and lists W5500-based adapters (including generic W5500 modules and W5500 Pico-form-factor boards) as the recommended way to add Ethernet to boards that don’t have it natively.

In the RP2040 firmware, W5500 is not just a hardware suggestion—it’s implemented as a concrete transport option:

• the repo vendors WIZnet ioLibrary_Driver as a submodule for the RP2040 firmware,
• and provides a dedicated W5500 UDP transport for micro-ROS (“custom transport over W5500 ethernet using UDP”).

This matches a common industrial robotics pattern: keep internal actuator/sensor networking wired (predictable latency, fewer RF failure modes), and keep operator/admin access on a separate network segment.

Implementation Notes

Snippet 1 — micro-ROS over UDP on W5500 (socket + DHCP + link checks)
File: saint_os/firmware/rp2040/transport/transport_w5500.c

// micro-ROS custom transport over W5500 ethernet using UDP.
// Uses WIZnet ioLibrary for DHCP and socket operations.

// Socket allocation (W5500 has 8 sockets: 0-7)
#define DHCP_SOCKET 6
#define UROS_SOCKET 0

while (!wizchip_port_link_up()) { /* ...timeout... */ }

if (g_node.use_dhcp) {
  if (run_dhcp(DHCP_TIMEOUT_MS)) { connected = true; return true; }
}
use_static_ip();  // fallback

int8_t result = socket(UROS_SOCKET, Sn_MR_UDP, UROS_LOCAL_PORT, 0);

Snippet 2 — RP2040 port layer for WIZnet ioLibrary (SPI callbacks + buffer sizing + chip detect)
File: saint_os/firmware/rp2040/transport/wizchip_port.c

// Register callbacks with ioLibrary
reg_wizchip_cs_cbfunc(wizchip_cs_select, wizchip_cs_deselect);
reg_wizchip_spi_cbfunc(wizchip_spi_readbyte, wizchip_spi_writebyte);

// Initialize W5500 (2KB per socket RX/TX)
uint8_t memsize[2][8] = {
  {2,2,2,2,2,2,2,2},
  {2,2,2,2,2,2,2,2}
};
if (ctlwizchip(CW_INIT_WIZCHIP, (void*)memsize) == -1) return false;

// Check chip version (W5500 expects 0x04)
uint8_t version = getVERSIONR();
if (version != 0x04) return false;

Practical Tips / Pitfalls

Put CS and RESET on dedicated GPIOs and treat reset as a recovery tool, not just a bring-up step (the RP2040 port does a hardware reset before init).

Decide early whether your nodes are DHCP-first or static-first, and document the fallback behavior (this repo implements DHCP with a static IP fallback).

Be intentional about socket allocation: reserve one socket for DHCP and one for micro-ROS transport (the code does this explicitly).

Start with conservative SPI clocking, then validate under motor/EMI conditions; the RP2040 port initializes SPI at 10 MHz.

If you run a dual-network robot, keep the internal node network isolated (different subnet/VLAN) from operator/admin traffic, and treat the server as the policy boundary.

FAQ

Q1. Why use W5500 for SAINT.OS nodes instead of Wi-Fi on Pico W-class boards?
SAINT.OS calls for wired Ethernet on the internal node network, and the RP2040 firmware implements micro-ROS transport over UDP on W5500. In practice, wired links reduce variability from RF congestion and make link status (“up/down”) a real signal you can gate control on—something the transport code already does before attempting DHCP or opening sockets.

Q2. How does the W5500 connect to the RP2040 in this project?
Via SPI, with explicit CS and RESET GPIO handling. The RP2040 port registers SPI read/write callbacks and CS select/deselect callbacks for WIZnet ioLibrary, then performs a hardware reset and initializes the W5500.

Q3. What role does W5500 play in THIS project’s runtime data flow?
It is the network interface for microcontroller nodes: the node brings up Ethernet (link → DHCP/static) and then opens a UDP socket used by a custom micro-ROS transport. The server side runs a micro-ROS agent that bridges those microcontroller nodes into the ROS2 graph.

Q4. Can beginners use this repo as a starting point for W5500 + micro-ROS?
Yes, if they’re comfortable with embedded bring-up. The repo includes a W5500-specific transport and an RP2040 ioLibrary port, which is the hard part most people end up re-implementing. Expect to spend time validating SPI wiring, reset timing, and IP provisioning in your target enclosure.

Q5. What’s the key trade-off versus using a software TCP/IP stack (or Wi-Fi) on the MCU?
The W5500 approach moves Ethernet + socket semantics into a dedicated controller and uses ioLibrary socket APIs on the MCU side, while SAINT.OS standardizes node comms around UDP micro-ROS. Compared to Wi-Fi, you trade cabling for predictable internal networking; compared to a pure software stack, you trade some flexibility for a narrower, more controlled networking surface area on the node