Skip to content

YAFU — User Runbook (concise, actionable)

This runbook describes two ways to update Ethernet boards with YAFU:

  • Method A — Parallel orchestrator (recommended for fleets): run yafu_parallel.sh which discovers IPs from a network XML and performs a 3‑phase update (prepare → program → restart) in parallel.
  • Method B — Stepwise control: use yafu_program.sh to prepare and program explicit IPs, then yafu_restart.sh to bring them back to application mode.

Note

Method B is a forced, user-driven workflow — it does not perform automatic firmware-version pre‑checks across targets. Use this when you need explicit control or to recover a single board. You may target one or multiple IP addresses; the scripts will act on the provided list.

All logs are written per‑IP under tools/yafu/logs with dots replaced by underscores (e.g. 10_0_1_2.log).

Prerequisites

  • Built executable: ../robotology-superbuild/build/src/ICUB/bin/yafu (executable). The scripts (yafu_*.sh) invoke this YAFU executable from the bin folder.
  • firmware.info.xml available and correct (see code or repo path).
  • Host can reach targets on UDP port 3333.
  • tools/yafu/logs is writable.

Runtime network XML resolution

Caution

yafu_parallel.sh resolves the network XML at runtime using YARP and the current robot name: 

NETWORK_XML="$(yarp resource --from "network.$YARP_ROBOT_NAME.xml" | grep '^\".*$' | sed 's/\"//g')"
- That returns the effective network file used by the robot (often under an install tree such as: ../robotology-superbuild/build/install/share/ICUBcontrib/robots/). - If you prefer a fixed file, set the env var before running: 
export NETWORK_XML=/path/to/network.setupFU.xml

Method A — Parallel orchestrator (single command)

What it does - Reads NETWORK_XML, extracts Ethernet <ataddress ip="..."> entries, and runs the three phases in parallel: 1. prepare: discover, version pre-check, ensure maintenance (eUpdater) 2. program: stream Intel HEX (PROG_START / PROG_DATA / PROG_END) to boards that need updating 3. restart: def2run + RESTART for successfully programmed boards

Quick usage 

cd ../robotology-superbuild/src/ICUB/src/tools/yafu
chmod +x yafu_parallel.sh
./yafu_parallel.sh

Exit codes (summary) - 0: all OK (or nothing needed) - 2: nothing prepared for programming (all skipped or failed) - 3: some programming failed - 4: fatal orchestrator error

Method B — Controlled per‑IP flow (program.sh + restart.sh)

What it does - Operator supplies IPs. yafu_program.sh puts each IP into maintenance if needed and programs it. yafu_restart.sh runs def2run + RESTART for given IPs.

Typical workflow 

cd ../robotology-superbuild/src/ICUB/src/tools/yafu
chmod +x yafu_program.sh yafu_restart.sh
./yafu_program.sh 10.0.1.2 10.0.1.3
./yafu_restart.sh 10.0.1.2 10.0.1.3
Examples - Single IP: 
./yafu_program.sh 10.0.1.1
./yafu_restart.sh 10.0.1.1
- Multiple IPs: 
./yafu_program.sh 10.0.1.1 10.0.1.2 10.0.1.3
./yafu_restart.sh 10.0.1.1 10.0.1.2 10.0.1.3

Extra perk — use the YAFU binary directly (no shell script)

If you prefer to run single commands without the shell orchestrator scripts, you can invoke the yafu executable directly from the bin folder. These commands map to the small helpers implemented in the code:

Notes:

  • The yafu binary sends UDP packets from the host using the host's source IP and ephemeral source port (or the interface forced by LOCAL_IP). Targets reply to that source socket. Running the binary directly behaves the same network-wise as the scripts. But this is single target not parallel or multi target approach

  • discover() -> discover

  • jump2updater() -> maintenance (request maintenance)
  • def2run_application() -> application (set application mode)
  • restart() -> restart
  • blink() -> blink

Example (run from the repository root or change path as needed):

cd ../robotology-superbuild/build/src/ICUB/bin/
chmod +x ./yafu

# Get full information about a board (DISCOVER):
./yafu discover 10.0.1.2

# Put a board in maintenance (request jumper to updater):
./yafu maintenance 10.0.1.2

# Put a board back to application mode (def2run):
./yafu application 10.0.1.2

# Restart the board (RESTART):
./yafu restart 10.0.1.2

# Blink the board LED (BLINK):
./yafu blink 10.0.1.2

Troubleshooting (concise)

  • No DISCOVER replies:
  • Check cabling, IP, host firewall
  • NETWORK_XML seems wrong: 
    yarp resource --from "network.$YARP_ROBOT_NAME.xml" | grep '^\".*$' | sed 's/\"//g'
less "$(yarp resource --from "network.$YARP_ROBOT_NAME.xml" | grep '^\".*$' | sed 's/\"//g' | head -n1)"
ls -l /usr/local/.../ICUBcontrib/robots/
  • If mismatched, set NETWORK_XML or fix the installed robot folder or YARP_ROBOT_NAME.
  • Firmware file not found:
  • Verify the <board type="..."> and <file> entries in your firmware.info.xml and that the file path resolves from the host.
  • Board won't enter maintenance:
  • Try restart.sh (single IP) or power-cycle

Wiring vs network‑file consistency

  • The network XML must reflect physical wiring (IP addresses, CAN IDs, board assignments).
  • If wiring changes, update the network XML and verify before running the updater. Quick checks: 
    # show resolved network resource(s)
yarp resource --from "network.$YARP_ROBOT_NAME.xml" | sed 's/"//g'

# inspect the resolved file (first match)
less "$(yarp resource --from "network.$YARP_ROBOT_NAME.xml" | sed 's/\"//g' | head -n1)"

# list installed robot folders (where deployed network files live)
ls -l ../robotology-superbuild/build/install/share/ICUBcontrib/robots/
  • Keep wiring diagrams and the exact network XML used for the run together for traceability: icub-tech-iit/electronics-wiring-public

Logs and escalation

  • Per‑IP logs: tools/yafu/logs/*.log — include these plus the firmware.info.xml board entry when asking for help.

Low-key

YAFU sends UDP messages from the host using the host's source IP and source port (or the interface forced by LOCAL_IP). Targets reply back to that source IP:port. The FirmwareUpdater GUI uses the well-known target port 3333 (each target IP is addressed on its configured destination port), so the GUI and YAFU operate on different directions/ports and do not conflict.

In short: you can keep the FirmwareUpdater GUI open while running YAFU — the target devices reply to YAFU's source socket, and the GUI's use of the predefined port (3333) does not cause socket errors for YAFU.

Avoid manually triggering conflicting actions from the FirmwareUpdater GUI at the exact same time you issue a program/restart command to the same target to prevent overlapping operations on the device.

Enjoy the YAFU - Yet Another Firmware Updater !!!!