Test Plan for the svah project
v0.5.2.86

• Any Linux host with GCC
• No special kernel modules
• No hardware

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

The test suite checks for vcan0 and skips integration tests gracefully if the interface is absent.

• ODrive motor controller (v3.6 or Pro)
• CAN transceiver connected to a Linux SocketCAN interface
• Motor mechanically free to rotate (calibration sequence)
• ODrive configured: node_id, bitrate, motor type

File

TestCanopenSimple.c

Function under test

CansimpMakeId, CansimpParseId

Method

construct known (axis_id, cmd_id) pairs; verify the 11-bit identifier; parse it back and verify round-trip.

Cases

axis_id	cmd_id	Expected msg_id
0	HEARTBEAT (0x001)	0x001
0	SET_INPUT_POS(0x00C)	0x00C
1	HEARTBEAT	0x021
3	SET_AXIS_STATE(0x7)	0x067
62	HEARTBEAT	0x7C1

Pass criterion

all round-trips exact; no assertion failures.

Function

CansimpEncodeSetInputPos

Method

encode known values; inspect payload bytes directly.

Cases

input_pos	vel_ff	torque_ff	Expected payload (hex, LE)
0.0f	0	0	00 00 00 00 00 00 00 00
1.0f	0	0	00 00 80 3F 00 00 00 00
-1.0f	100	50	00 00 80 BF 64 00 32 00

Pass criterion

byte-exact match with expected payload; DLC = 8; isExtended = 0; isRemote = 0.

Function

CansimpEncodeSetInputVel

Method

encode known values; verify payload.

Cases

vel	torque_ff	Expected payload bytes 0..7
0.0f	0.0f	all zeros
10.0f	0.0f	0x41200000 at [0..3]

Pass criterion

byte-exact payload; DLC = 8.

Function

CansimpEncodeSetAxisState

Cases

State	Expected payload [0..3]
AXIS_STATE_IDLE (1)	01 00 00 00
AXIS_STATE_CLOSED_LOOP(8)	08 00 00 00

Pass criterion

byte-exact; DLC (Data Length Code) = 4. The DLC is the 4-bit CAN frame field indicating the number of payload bytes (0..8). See Glossary.

Function

CansimpDecodeHeartbeat

Method

construct raw HalCanFrame with known payload; decode; verify output fields.

Cases

Payload (hex)	axis_error	state	proc_result	traj_done
00000000 01 00 00	0	IDLE	0	0
00000000 08 00 01	0	CL	0	1
01000000 01 04 00	1	IDLE	4	0

Error cases

NULL frame → -1; DLC < 6 → -1; wrong cmd_id → -1.

Pass criterion

all fields exact; error cases return -1.

Function

CansimpDecodeEncoderEstimates

Method

build frame with known float payload; decode and compare with fabsf(result - expected) < 1e-6f.

Cases

pos_estimate	vel_estimate
0.0f	0.0f
1.5f	-2.0f
100.0f	50.25f

Pass criterion

float comparison within tolerance; error on wrong cmd_id or short DLC.

Functions

CansimpDecodeIq, CansimpDecodeTemperature, CansimpDecodeBusVoltageCurrent

Method

same as UT-06, with the corresponding cmd_ids and field meanings.

Pass criterion

float round-trip within 1e-6; wrong cmd_id returns -1.

File

TestHalTime.c

Functions

HalTimeMs, HalTimeUs

Method

call each function twice with a nanosleep delay of 10 ms between calls; verify t2 >= t1 and (t2 - t1) is within [5, 50] ms.

Pass criterion

monotonicity holds; difference in expected range.

File

TestOdriveApi.c

Function

OdriveAxisInit

Method

pass NULL pointers; verify ODRIVE_ERR_PARAM. Pass valid (mock) handle; verify all fields zero-initialised and axisId set correctly.

Pass criterion

return codes and field values as expected.

Function

OdriveProcessFrame

Method

construct synthetic frames for each handled cmd_id; call OdriveProcessFrame; verify the corresponding OdriveAxis fields are updated. Also verify frames for a different axis_id return 1 (ignored).

Pass criterion

field updates correct; ignored frames return 1; malformed frames return -1.

Requires

vcan0 interface up

Method

1. Open two handles on vcan0 (sender and receiver).
2. Enable CAN_RAW_RECV_OWN_MSGS on sender so it receives its own frames (loopback, using setsockopt).
3. Transmit a known frame on the sender handle.
4. Receive on the sender (loopback) and on the receiver handle.
5. Verify frame contents match exactly.
6. Close both handles.

Pass criterion

transmitted frame received intact on both sides; no error return codes.

Method

transmit HAL_CAN_RX_BUFFER_SIZE + 4 frames on a loopback socket without calling HalCanReceive; then drain the buffer. Verify that exactly HAL_CAN_RX_BUFFER_SIZE frames are returned (oldest dropped, warning on stderr).

Pass criterion

buffer returns exactly buffer-size frames; overflow is not fatal.

Method

register a callback that increments a counter and stores the last frame; transmit 5 frames; call HalCanReceive once (should return HAL_CAN_NO_FRAME since callback consumed them); verify counter = 5 and last frame matches.

Pass criterion

callback invoked for each frame; polling returns no frame after callback consumption.

Method

1. Open vcan0; initialise an OdriveAxis.
2. In a separate thread, listen for a Set_Axis_State frame and respond with a synthetic Heartbeat confirming the new state.
3. Call OdriveSetAxisState(AXIS_STATE_IDLE, 500) from the main thread.
4. Verify the function returns ODRIVE_OK and axis.lastState equals AXIS_STATE_IDLE.

Pass criterion

state transition completes within timeout; axis state updated.

Method

call OdriveSetAxisState with a 100 ms timeout but inject no heartbeat response. Verify the function returns ODRIVE_ERR_TIMEOUT within 150 ms.

Pass criterion

timeout returned; elapsed time within acceptable bounds.

Requires

vcan0 up (see vcan0 setup); ./svah built.

Source

TestSvah.c, function TestSvahNoMotion.

Method

1. Open a raw SocketCAN socket on vcan0 in a POSIX thread (minimal simulator).
2. The thread listens for a Set_Axis_State frame and responds with a synthetic Heartbeat confirming the requested state.
3. Fork svah --interface vcan0 --axis 0 --no-motion --quiet.
4. Collect exit status of svah and simulator thread.

Pass criterion

svah exits 0; simulator received Set_Axis_State frame.

Requires

none.

Source

TestSvah.c, function TestSvahBadInterface.

Method

run svah --interface nonexistent99 --no-motion.

Pass criterion

svah exits non-zero.

Requires

vcan0 up (see vcan0 setup); ./svahsim built.

Source

TestSvahSim.c, function TestSvahSimPlayMode.

Method

1. Write a minimal play-mode .svs script (no EXPECT directives) to a temporary file.
2. Run svahsim --interface vcan0 <script>.
3. Verify exit status 0.

Pass criterion

svahsim exits 0 after all AT events fire.

Requires

vcan0 up (see vcan0 setup); ./svah and ./svahsim built.

Objective

validate the full stack (HalCan → CanopenSimple → OdriveApi → svah) against the ODrive simulator, without physical hardware.

Source

TestSvahSim.c, function TestSvahSimWithSvah.

Method

1. Launch svahsim as background with a script that declares an ON SET_AXIS_STATE DO CONFIRM_STATE DELAY 30 rule and several AT heartbeat events.
2. After 50 ms, launch svah --interface vcan0 --no-motion --quiet.
3. Collect exit status of both processes.

Pass criterion

both processes exit 0.

Sequence diagram

see Two-Process Test Architecture in SimScriptLanguage.org.

:ID: ST-01 :CUSTOM_ID: ST-01

Before running any system test, the ODrive S1 must be configured for CAN via odrivetool. This is a one-time procedure; the configuration is saved to non-volatile memory on the ODrive.

Requires

• ODrive S1 configured for CAN (see ODrive S1 CAN configuration)
• CAN bus wired and terminated (Option A or B above)

• can0 interface up at 250 kbps on host:

  sudo ip link set can0 type can bitrate 250000
  sudo ip link set up can0
  

Objective

verify that the ODrive S1 emits CANSimple heartbeat frames at the configured rate and that libsvah decodes them correctly.

Method

1. Use candump in parallel to cross-check raw frames:

   candump can0 &
   

2. Run svah in no-motion mode with debug logging:

   svah --interface can0 --axis 0 --no-motion --log-on-stderr --debug
   

3. Observe heartbeat messages on stderr.
4. Kill candump.

Pass criterion

• svah receives at least one heartbeat within the default timeout (2000 ms) and exits 0.
• Heartbeat rate visible in candump output (~10 Hz, i.e. one frame every ~100 ms on CAN ID 0x001).
• No ODrive error flags reported (error flags: 0x00000000).

Expected svah output

svah VERSION — iface: can0  bitrate: 250000 bps  axis: 0
[svah INFO] HalCanInit: opened can0 (...)
svah: requesting IDLE on axis 0...
svah: axis 0 is IDLE  (error flags: 0x00000000)
svah: --no-motion — done

Requires

ST-01 passed; same hardware setup.

Objective

verify that svah can command the ODrive S1 to enter AXIS_STATE_IDLE and receive the confirming heartbeat.

Method

svah --interface can0 --axis 0 --no-motion --log-on-stderr

Pass criterion

exit status 0; output shows axis 0 is IDLE; no error flags.

Distinguishes from PI tests

a real ODrive controller responds to SET_AXIS_STATE with its actual firmware state machine. The confirming heartbeat is generated by the ODrive firmware, not by svahsim. Timing and error flags reflect the real hardware.

Requires

motor calibrated

Method

extend svah with --state closed-loop option (future). Send position setpoint 0.0 turns; verify encoder estimates return to 0.0 ± 0.01 turns within 2 s.

Pass criterion

position settled; no ODrive error flags.

See FutureResearch.org entry on DBC cross-validation. Write a script that encodes each CANSimple message with known inputs and compares the resulting payload against the signal definitions in the ODrive .dbc file for the target firmware version.

The check_PROGRAMS automake variable builds and runs unit tests. Each test program exits with status 0 on success, non-zero on failure. Integration tests check for vcan0 availability and exit 77 (automake skip code) if absent.

Both adapters use the same gs_usb kernel driver and appear as a standard SocketCAN can0 interface. The procedure is therefore identical on both hosts.

Termination note: a two-node bus requires one 120 Ω resistor at each end. The DSD TECH SH-C31A has two white slide switches; termination is enabled by lowering the right-hand switch (when facing the screw terminal block). The ODrive USB-CAN Adapter has a single black sliding switch; termination is enabled by pushing it toward the screw terminal block. Both must be enabled. If a scope is available, verify the bus idle voltage: CANH ≈ 2.5 V, CANL ≈ 2.5 V, differential ≈ 0 V at idle; ≈ 2 V during a dominant bit.

The photographs below show the actual wiring and switch positions used for PI-01 and PI-02.

Wiring colour code in both photographs: red = CANH, blue = CANL, black = GND. This colour code is not part of any standard; always verify wire assignment with a continuity meter before powering the bus.

Wiring: CAN 2.0B (ISO 11898-2) uses a differential pair — CANH and CANL are the two signal wires and form one twisted pair. GND is a third conductor, not part of the twisted pair. Use a 3-conductor cable: one twisted pair for CANH/CANL (the twist reduces common-mode noise) plus one additional straight wire for GND. A practical option is a CAT-5 cable using one pair (e.g. blue/white-blue) for CANH/CANL and one wire of a second pair (e.g. orange) for GND.

Connect CANH to CANH, CANL to CANL, GND to GND. Verify wire assignment with a continuity meter before powering the adapters. At 250 kbps this wiring is adequate up to several metres.

This section documents the setup of a Raspberry Pi 4 Model B with the Waveshare RS485 CAN HAT (B), used as System A or B in PI-03 (heterogeneous platform test).

Hardware: Waveshare RS485 CAN HAT (B) — SPI-connected MCP2515 CAN controller with 16 MHz oscillator. See: https://www.waveshare.com/wiki/RS485_CAN_HAT_(B)

Execute the following steps on both x86 hosts unless noted otherwise.

Requires

physical CAN bus up and verified (see Hardware configuration and Steps 1–3)

Objective

validate the full libsvah stack (HalCan → CanopenSimple → OdriveApi) across a real CAN bus, with no shared kernel between the two hosts.

Method

PhysicalTest drives both sides of the test. On System A, it launches svahsim with PhysicalNoMotion.svs, which declares an ON SET_AXIS_STATE DO CONFIRM_STATE rule and emits heartbeats for 1.5 s. On System B, it launches svah --no-motion, which requests AXIS_STATE_IDLE and exits 0 once the confirming heartbeat is received.

System A (start first):

./PhysicalTest --role sim --interface can0

System B (start after System A prints its ready message):

./PhysicalTest --role app --interface can0

Pass criterion

PhysicalTest --role app exits 0 on System B; PhysicalTest --role sim exits 0 on System A.

Requires

physical CAN bus up; PI-01 passed.

Objective

validate that periodic frames emitted by svahsim on System A arrive at System B with sufficient regularity to satisfy OdriveSetAxisState's polling loop within the 2 s timeout. This exercises timing that vcan0 cannot reproduce (vcan0 has zero propagation delay and no bus arbitration).

Method

same as PI-01 but with an extended timeout on System B. PhysicalNoMotion.svs emits heartbeats at 100 ms intervals; the 2 s timeout gives 20 heartbeat opportunities.

System A (start first):

./PhysicalTest --role sim --interface can0

System B:

./PhysicalTest --role app --interface can0 --timeout 2000

Monitor bus load on either host while the test runs:

canbusload can0@250000

Pass criterion

PhysicalTest --role app exits 0; no timeout errors in syslog.

Distinguishes from IT-09

propagation delay, bit stuffing overhead, and USB scheduling jitter on the physical bus make the timing non-trivial. Success confirms the timing budget is adequate for real deployment.

Requires

physical CAN bus; one PC x86 (System A or B); one Raspberry Pi (System B or A); Waveshare 2-ch FD HAT or SBC-CAN01 on the RPi (see FutureResearch.org for setup notes).

Objective

validate that libsvah produces correct frames on an ARM host and that the Linux/SocketCAN HAL works identically regardless of CPU architecture. Of particular interest: correctness of memcpy-based float encoding across endianness and alignment differences, and USB scheduling jitter from the RPi's USB-CAN interface.

Method

same as PI-01 using PhysicalTest, with the RPi playing one role and the x86 the other.

Configuration A — RPi as simulator (System A), x86 as application (System B):

# RPi (System A):
./PhysicalTest --role sim --interface can0
# x86 (System B):
./PhysicalTest --role app --interface can0

Configuration B — x86 as simulator, RPi as application:

# x86 (System A):
./PhysicalTest --role sim --interface can0
# RPi (System B):
./PhysicalTest --role app --interface can0

Pass criterion

both configurations pass with both roles on both platforms.

Minimal environment on ARM target

to run PhysicalTest on the RPi without a full project checkout, copy the following files:

1. The svahsim or svah binary (from .libs/ after cross-compilation)
2. The PhysicalTest script
3. The PhysicalNoMotion.svs script

The recommended approach is to include test files in the make install staging:

make -C build-aarch64 install DESTDIR=/tmp/svah-staging
# Add test scripts manually:
mkdir -p /tmp/svah-staging/usr/local/share/svah
cp PhysicalNoMotion.svs /tmp/svah-staging/usr/local/share/svah/
cp PhysicalTest /tmp/svah-staging/usr/local/bin/
rsync -av /tmp/svah-staging/usr/local/ pi@raspberrypi:/usr/local/
ssh pi@raspberrypi 'sudo ldconfig'

Then on the RPi, set SVAH or SVAHSIM if the binaries are not in /usr/local/bin:

export SVAHSIM=/usr/local/bin/svahsim
PhysicalTest --role sim --interface can0

(no term)

Results (2026-04-20, RPi 4 Model B + Waveshare RS485 CAN HAT (B)):

Configuration A — ARM (svahsim) ↔ x86 (svah):

ARM: svahsim PASS (1/1 assertions satisfied)
x86: svah 0.3.21.65 — PASS (svah exited 0)

Configuration B — x86 (svahsim) ↔ ARM (svah):

x86: svahsim PASS (1/1 assertions satisfied)
ARM: svah 0.3.21.65 — PASS (svah exited 0)

Both configurations PASS. The memcpy-based float encoding is correct on ARM (little-endian, same as x86). The MCP2515 SPI HAL introduces no frame corruption within the 2 s timeout budget.

Status

PASS (both configurations, 2026-04-20, RPi 4 running GNU/Linux Debian trixie 13.4).

Requires

physical CAN bus; PI-01 passed.

Objective

validate that svah detects and reports an ODrive error condition injected by svahsim, and exits with a non-zero status.

Method

a dedicated .svs script emits a heartbeat with a non-zero error field before responding to SET_AXIS_STATE. svah must detect the error flag in the heartbeat and report it.

./PhysicalTest --role sim --interface can0          --script ErrorInjection.svs
./PhysicalTest --role app --interface can0

Pass criterion

svah exits non-zero and logs the error flags; svahsim exits 0.

Status

planned; requires ErrorInjection.svs to be adapted for the physical test scenario.

Requires

physical CAN bus; PI-01 passed.

Objective

validate that svah detects a bus interruption (cable pulled) and exits with ODRIVE_ERR_TIMEOUT, without hanging indefinitely.

Method

1. Start System A (svahsim) normally.
2. Start System B (svah --timeout 2000).
3. Disconnect the CAN cable approximately 500 ms after System B starts (after the first heartbeat is received but before the confirming heartbeat).
4. Observe exit codes and syslog on System B.

Pass criterion

svah exits non-zero within timeout + 200 ms; syslog shows a timeout error; no hang.

Script

use LongCycle.svs (60 s duration) to give the operator sufficient time to disconnect the cable:

System A:

./PhysicalTest --role sim --interface can0          --script LongCycle.svs

System B:

./PhysicalTest --role app --interface can0 --timeout 2000 --hold 60

The --hold 60 keeps svah on the bus for 60 s after the IDLE transition, polling heartbeats. Disconnect the CAN cable approximately 5 s after System B starts; svah exits non-zero when the next heartbeat times out.

(no term)

Results (2026-04-20, x86 sim ↔ ARM app):

System A (x86, svahsim, LongCycle.svs):

svahsim 0.3.24.72 — iface: can0  axis: 0
svahsim: running script 'LongCycle.svs' (play mode)
[svah ERROR] HalCanReceive: read() failed: No such device
[svah ERROR] HalCanTransmit: write() failed: No such device or address
...
svahsim: PASS (play mode — no assertions)

System B (ARM, svah, --hold 60):

svah 0.3.24.72 — iface: can0  bitrate: 250000 bps  axis: 0
svah: requesting IDLE on axis 0...
svah: axis 0 is IDLE  (error flags: 0x00000000)
svah: --no-motion — done
svah: --hold 60 — monitoring bus for 60 s
svah: disconnect the CAN cable now to test bus disruption
[svah ERROR] OdriveWaitHeartbeat: timeout
[svah ERROR] svah: bus disruption detected — heartbeat timeout (-2)
svah: bus disruption detected — heartbeat timeout
PhysicalTest: FAIL — svah exited 1

(no term)

Behaviour notes:

• svah exits non-zero as expected when the cable is disconnected during the hold window. PI-05 PASS from System B's perspective.
• svahsim continues running until all AT events in LongCycle.svs have fired (60 s). This is nominal in play mode: the script has no EXPECT assertions, so svahsim has no way to detect the cable disconnect and runs to completion. The HalCanReceive / HalCanTransmit errors on System A are diagnostic messages from failed I/O after the adapter is removed by the kernel.

Status

PASS (System B, 2026-04-20). svahsim play-mode behaviour on cable disconnect documented above.

(no term)

Symmetric detection (0.3.30): the play-mode limitation above is now optional. To have the simulator side also detect the disconnect and exit non-zero, either run an assertion-mode script with EXPECT CONNECTED WITHIN N (BusWatch.svs), or add --bus-timeout N to any script invocation:

# Assertion-mode simulator side:
./PhysicalTest --role sim --interface can0 --script BusWatch.svs
# or wrap the play-mode script with a timeout:
svahsim --interface can0 --bus-timeout 2000 LongCycle.svs

With either, System A exits non-zero on disconnect, making PI-05 symmetric. See SimScriptLanguage.org for the directive and option.

Requires

physical CAN bus; two adapters with independently configurable bitrates.

Objective

validate that configuring one host at 250 kbps and the other at 500 kbps produces bus errors detectable via ip -s link show can0 (error counters) and that neither host hangs.

Method

# System A: 250 kbps (correct)
sudo ip link set can0 type can bitrate 250000
sudo ip link set up can0
./PhysicalTest --role sim --interface can0

# System B: 500 kbps (intentionally wrong)
sudo ip link set can0 type can bitrate 500000
sudo ip link set up can0
./PhysicalTest --role app --interface can0

(no term)

Observed behaviour (2026-04-20):

System A (x86, 250 kbps)

svah exits non-zero (timeout). ip -s link show can0 shows zero CAN errors on System A. Reason: the x86 transmits correctly at 250 kbps; the ARM frames at 500 kbps are not valid CAN frames at 250 kbps and are ignored by the x86 controller.

System B (ARM, 500 kbps)

repeated HalCanTransmit: write() failed: No buffer space available. The MCP2515 enters error-passive or bus-off state because its 500 kbps frames cannot be acknowledged on a 250 kbps bus. The TX queue fills up.

Pass criterion

svah exits non-zero on System A; System B produces TX errors indicating bus-off. Neither host hangs.

Note on adapter behaviour

the MCP2515 (RPi Waveshare HAT) enters bus-off after sustained errors. The USB-CAN adapters using gs_usb on the x86 side remain operational. After the test, restart the ARM interface: sudo ip link set can0 down then sudo ip link set can0 up.

Status

executed 2026-04-20; results documented above.

The vcan0 virtual CAN interface is required for all integration tests IT-01 through IT-09. It is provided by the vcan kernel module and has no hardware dependency.

The following packages are needed on Ubuntu/Debian:

Install all at once:

sudo apt install gcc make autoconf automake libtool libtool-bin        libreadline-dev libncurses-dev can-utils

Documentation build only:

sudo apt install emacs-nox plantuml        texlive-latex-extra texlive-fonts-recommended

Each test program executed by make check produces two files in the build directory:

TestName.log

Standard output and standard error of the test program, captured by the automake test harness. Contains the full test output (individual test names, PASS/FAIL lines, results summary). Useful for diagnosing failures.

TestName.trs

Machine-readable test result file in the Test Result Summary format used by automake. Contains one line per test: :test-result: PASS, :test-result: FAIL, or :test-result: SKIP. Read by automake to build the test-suite.log summary.

test-suite.log

Overall test summary produced by automake. Contains the result counts (TOTAL / PASS / SKIP / FAIL) and concatenates the output of any failed test programs.

These files are removed by make clean (they are in CLEANFILES).

The automake skip code is 77: a test program that exits with status 77 is reported as SKIP, not FAIL. This is used by TestHalCanLinux and TestSvah when vcan0 is absent.