Skip to content

Latest commit

 

History

History
144 lines (101 loc) · 4.84 KB

example-packets.md

File metadata and controls

144 lines (101 loc) · 4.84 KB

ExamplePackets

Purpose

ExamplePackets is the packet and order parsing validation example built on top of generated OrderPackets and DataPackets.

It validates:

  • TCP order parsing through the generated ServerSocket
  • UDP packet parsing through the generated DatagramSocket
  • board-to-host TCP client traffic through Socket
  • generated enum and scalar serialization for bool, signed integer, unsigned integer, floating-point, and enum fields
  • parser robustness under fragmented TCP writes
  • autogenerated socket instantiation from ADJ
  • autogenerated periodic packet scheduling through Scheduler

ADJ dependency

This example is tied to the current packet schema used in this branch.

It is not schema-agnostic.

The required ADJ branch for this example is:

  • fw-test-packets

It expects the active ADJ checkout to generate the TEST board packet API used by this example and by tools/example_packets_check.py.

Concretely:

  • BOARD_NAME must resolve to the current TEST board definition
  • the generated OrderPackets / DataPackets set must include the packet/order names used by this source
  • if you switch ADJ to a different branch for another application, this example may stop compiling or the checker may stop matching

This is the branch/schema that currently matches:

  • current Core/Inc/Code_generation/JSON_ADE contents in this repo
  • current boards.json selection that exposes only TEST

If that ADJ content changes, regenerate and verify that these generated symbols still exist before using the example:

  • OrderPackets::set_small_profile_*
  • OrderPackets::set_large_profile_*
  • OrderPackets::set_extremes_*
  • OrderPackets::bump_state_*
  • OrderPackets::set_state_code_*
  • DataPackets::order_mirror_*
  • DataPackets::numeric_mirror_*
  • DataPackets::extremes_mirror_*
  • DataPackets::udp_probe_*
  • DataPackets::heartbeat_snapshot_*
  • DataPackets::telemetry_udp
  • OrderPackets::control_test_tcp
  • OrderPackets::control_test_client

Build

Nucleo Ethernet build:

./tools/build-example.sh --example packets --preset nucleo-debug-eth

Equivalent macro selection:

  • EXAMPLE_PACKETS
  • BOARD_NAME=TEST

Network configuration

Fixed board configuration:

  • Board IP: 192.168.1.7
  • UDP DatagramSocket (telemetry_udp): 41001
  • TCP ServerSocket (control_test_tcp): 41000
  • TCP Socket (control_test_client) local/remote: 41002 / 41003
  • Host link IP expected by generated sockets: 192.168.1.9

Runtime behavior

The example:

  • starts generated OrderPackets and DataPackets
  • accepts TCP orders on the generated control server
  • accepts TCP orders on the board-initiated generated client socket once connected
  • receives and sends UDP packets through the generated DataPackets::telemetry_udp
  • relies on ADJ packet metadata so DataPackets::start() registers periodic send tasks in Scheduler
  • publishes order_mirror, numeric_mirror, extremes_mirror, and udp_probe_echo periodically at 50 ms
  • publishes heartbeat_snapshot periodically at 250 ms
  • recreates the generated control ServerSocket in the example if the test client disconnects

Orders exercised by the checker:

  • set_small_profile
  • set_large_profile
  • set_extremes
  • bump_state
  • set_state_code

Data packets emitted by the firmware:

  • order_mirror
  • numeric_mirror
  • extremes_mirror
  • udp_probe_echo
  • heartbeat_snapshot

How to validate

  1. Configure the host-side board-link interface with IPv4 192.168.1.9.
  2. Build and flash the example.
  3. Run the checker:
./tools/example_packets_check.py --board-ip 192.168.1.7 --host-bind 192.168.1.9 --iterations 25

When the host also has Wi‑Fi on 192.168.1.x, binding to 192.168.1.9 is important. It forces the host-side TCP and UDP traffic to use the Nucleo link while leaving the Wi‑Fi route untouched.

Useful stress knobs:

  • --chunk-max: maximum TCP fragment size used by the checker
  • --chunk-gap-ms: delay between fragments
  • --connect-settle: delay after connect before sending

What the checker validates

  • TCP fragmented order parsing still reconstructs full orders correctly.
  • UDP probe packets are parsed into the right generated fields.
  • The scheduler-driven UDP DatagramSocket sends the expected generated DataPackets on the configured periods.
  • The board TCP client path reaches the host listener and accepts orders over the board-initiated Socket.

Expected result

  • All iterations pass.
  • No hard fault.
  • No corrupted fields in integer, floating-point, or enum values.

What a failure usually means

  • TCP mismatch only: stream reassembly or order parsing issue.
  • UDP mismatch only: packet layout, endianness, or field offset issue.
  • Client-path mismatch only: board Socket reconnect/send path issue.
  • Hard fault: usually packet access, alignment, or invalid pointer handling in serialization.