What we will do: turn an interface control document (ICD) table into a project, add an interface, and meet the
parts of a model. This chapter makes a second project next to drone; chapter 4 continues with drone.
Many teams keep their messages in a spreadsheet. WireForge reads such a table as CSV or Excel (and C headers and CAN
databases, see the import guide). Save this table as sensor.csv:
cat > sensor.csv <<'CSV'
section,name,id,field,type,bits,occurs,count,min,max,default,units,description
type,Vec3,,x,f32,,,,,,0.0,m/s2,X axis
type,Vec3,,y,f32,,,,,,0.0,m/s2,Y axis
type,Vec3,,z,f32,,,,,,0.0,m/s2,Z axis
message,ImuSample,0x0110,sensorId,u8,,,,1,32,1,,Sensor number
message,ImuSample,,accel,Vec3,,,,,,,,Acceleration
message,ImuSample,,temperature,f32,,,,-40,125,20,degC,Die temperature
message,Heartbeat,0x0001,uptime,u32,,,,,,,s,Seconds since start
CSV
wireforge import-icd sensor.csv sensor --name sensor --namespace demo::sensor --endian littleEvery row is one field of a type or message; min, max and default become checks and initial values of the
generated code.
A message alone has no frame. An interface says how messages travel: a header, a trailer and how frames are found in a byte stream. This one has a sync word, a message id and a length, and a CRC-32 at the end:
wireforge upsert sensor checksums crc '{ algo: crc32 }'
wireforge upsert sensor interfaces imu_link '{ version: "1.0.0", direction: rx, header: { fields: [{ name: sync, type: u16, const: 0xA55A, role: sync }, { name: msgId, type: u16, role: message_id }, { name: length, type: u8, role: payload_length }] }, trailer: { fields: [{ name: crc, type: u32, checksum: { use: crc, covers: { scope: header_and_payload } } }] }, framing: { kind: sync_length, max_frame_size: 64, resync: true }, messages: [ImuSample, Heartbeat] }'
wireforge validate sensor
wireforge encode sensor ImuSample '{ sensorId: 3, temperature: 21.5 }' --interface imu_linkresync: true lets a receiver find the next frame after garbage or a broken frame.
MAVLink keeps its messages in XML files, the dialects: common.xml, ArduPilot's ardupilotmega.xml or your own.
wireforge import-mavlink turns a dialect and the files it includes into a project with every message and enum, the
fields in the order MAVLink sends them and the checksum byte of every message computed from its definition. pymavlink
ships the dialects, so take them from there:
python -m pip install pymavlink
DIALECTS="$(python -c 'import os, pymavlink; print(os.path.dirname(pymavlink.__file__))')/dialects/v20"
wireforge import-mavlink "$DIALECTS/common.xml" mavlink --name mavlink
wireforge import-mavlink "$DIALECTS/ardupilotmega.xml" apm --name apm --message HEARTBEAT --message AHRS2
wireforge encode mavlink SysStatus '{ voltageBattery: 12600, batteryRemaining: 87 }' --interface linkmavlink/ has the 210 messages of common.xml; apm/ has only the two messages asked for (and the enums they
use). Both have the frame of the drone project, so chapter 4 works with them the same way. Import the dialect again
when it changes: the project follows it.
| Part | What it is | Example |
|---|---|---|
types |
a struct used by messages | Vec3 |
messages |
what is sent, with a message id | ImuSample |
enums |
named values of an integer field | FixType |
checksums |
CRCs or your own algorithm | crc32, MAVLink's checksum |
interfaces |
header, trailer, framing and the messages of one link | imu_link, link |
profiles |
platform variants: defines and conditional fields | platformA |
Fields can be bit-fields (bits: 3), arrays of fixed or counted size (occurs), optional, conditional on a profile
(if:), scaled (scale: 1.0e-7 for degrees sent as integers) or constant. The wire format is always the one you
describe: WireForge never adds bytes.
Look at the generated code of the new project:
wireforge generate sensor -o build/sensorMore: definition format, importers, examples.
If something goes wrong: import-icd reports the row of every problem. A message that does not fit
max_frame_size is refused with the size it needs.
Next: 4. Use the code