What we will do: build a small vehicle that speaks MAVLink 2 over UDP with the code generated from drone, and
check it with pymavlink, an independent MAVLink implementation. The vehicle sends HEARTBEAT, ATTITUDE and VFR_HUD and
answers COMMAND_LONG with COMMAND_ACK.
The application is in the WireForge repository, examples/tutorial/drone_app/: three files, CMakeLists.txt,
main.cpp and udp_transport.hpp, plus ground_station.py. Its C version and the firmware of chapter 5 are next to
it.
git clone --depth 1 https://github.com/oguzhankynk/wireforge.git wireforge-srccp -r wireforge-src/examples/tutorial/drone_app wireforge-src/examples/tutorial/drone_app_c .cmake -S drone_app -B build/drone_app -DDRONE_PROJECT="$PWD/drone" -DWireForge_DIR="$(wireforge cmake-dir)"
cmake --build build/drone_appfind_package(WireForge) finds the CMake package that comes with WireForge, and one line in CMakeLists.txt generates
the code from your model when CMake configures the build:
wireforge_generate(drone_model PROJECT "${DRONE_PROJECT}")
target_link_libraries(drone_sim PRIVATE drone_model)Change the model and build again: the code follows.
python -m pip install pymavlink
build/drone_app/drone_sim 6 & python drone_app/ground_station.py; waitThe vehicle sends for six seconds; the ground station waits for its HEARTBEAT, sends COMMAND_LONG 400 (arm), and checks that COMMAND_ACK, ATTITUDE and VFR_HUD arrive:
ground station: HEARTBEAT from system 1, type 2
ground station: ATTITUDE {'time_boot_ms': 1000, 'roll': 0.168..., 'pitch': 0.054..., 'yaw': 0.0, ...}
ground station: VFR_HUD {'airspeed': 0.0, 'groundspeed': 0.0, 'heading': 10, 'throttle': 0, 'alt': 10.47..., ...}
vehicle: COMMAND_LONG 400 (param1 1), answering COMMAND_ACK
ground station: COMMAND_ACK {'command': 400, 'result': 0, 'progress': 0, ...}
ground station: all messages arrived
vehicle: done, 91 frames sent, ground station seen
vehicle: link sent 91, received 2, unknown id 0
pymavlink was not written with WireForge, so this is a real interoperability check: the frames, the trimmed payloads and the checksums are the ones every MAVLink tool expects. Ground station software such as QGroundControl listens on the same UDP port 14550.
The handler receives decoded messages. Every message of the model has a callback, so adding a message to the model asks you, at compile time, what the application does with it:
namespace mav = drone::mavlink2;
namespace link = mav::link;
class Vehicle final : public link::Handler {
public:
void onCommandLongReceived(const mav::CommandLong& command) noexcept override { /* ... */ }
void onVfrHudReceived(const mav::VfrHud& /*message*/) noexcept override {}
// ... one callback per message
};The endpoint joins the frame decoder, the dispatcher and the handler; the link reads a transport and sends frames:
UdpTransport transport(14551, 14550);
Vehicle vehicle;
link::Endpoint endpoint(vehicle);
link::Link<UdpTransport> channel(transport, endpoint.decoder(), endpoint.dispatcher());
mav::Attitude attitude{};
attitude.roll = 0.2F;
channel.send([&](wireforge::Span<std::uint8_t> buffer, std::size_t& size) {
return link::encode_frame(attitude, buffer, size, header);
});
channel.poll(); // reads what arrived and calls the handlerA frame that reaches no callback (an id the model does not know) goes to onUnhandled, whose default only lets the
link count it. The vehicle overrides it to write a line with its own log function (in C the handler has an
on_unhandled callback, NULL meaning "only count"). The link also counts what it did: channel.counters() has the
frames sent and received, the frames rejected by the frame decoder and the unknown ids, and the last line of the
program prints three of them.
A transport is any class with a non-blocking send and receive (udp_transport.hpp is 60 lines); on a
microcontroller it is a UART or a CAN driver. Nothing allocates memory, nothing throws, and trimming the trailing zeros
of MAVLink 2 is done by the generated code: the application never sees it.
drone_app_c/ is the same vehicle in C99. One option of wireforge_generate makes the generated code C, and the
library becomes a static library of the generated sources:
wireforge_generate(drone_model PROJECT "${DRONE_PROJECT}" LANGUAGE c)cmake -S drone_app_c -B build/drone_app_c -DDRONE_PROJECT="$PWD/drone" -DWireForge_DIR="$(wireforge cmake-dir)"
cmake --build build/drone_app_c
build/drone_app_c/drone_sim_c 6 & python drone_app/ground_station.py; waitThe ground station sees the same messages. In C the handler is a struct of callbacks, and a callback left NULL
means "decode and ignore", so the vehicle sets only the two it acts on:
self->handler.context = self;
self->handler.on_Heartbeat_received = on_heartbeat;
self->handler.on_CommandLong_received = on_command_long;
drone_mavlink2_link_link_init(&self->link, transport, &self->handler);The vehicle itself (vehicle.c) knows nothing about UDP: main.c gives it a transport and calls vehicle_tick()
every 10 ms. That is what lets the next chapter run it on a microcontroller.
WireForge does not generate Rust, but the generated C code works from it, also in no_std: it needs no heap and no
standard library. drone_app_rust/ is the same vehicle in Rust. Its build.rs runs wireforge generate --language c,
compiles the C code with the cc crate and writes the declarations with bindgen. With Rust, a C compiler and libclang
installed:
cp -r wireforge-src/examples/tutorial/drone_app_rust .
DRONE_PROJECT="$PWD/drone" cargo build --manifest-path drone_app_rust/Cargo.toml --release
drone_app_rust/target/release/drone_sim_rust 6 & python drone_app/ground_station.py; waitThe ground station sees the same messages. The transport and the handler are extern "C" functions that get a context
pointer, and the rest are the C functions of this chapter:
let transport = wf_transport { context, send: Some(udp_send), receive: Some(udp_receive) };
handler.on_CommandLong_received = Some(on_command_long);
drone_mavlink2_link_link_init(link.as_mut_ptr(), &transport, &handler);These calls are unsafe: the generated API is C, so a safe wrapper for your application is yours to write. The library
(src/lib.rs) is no_std, and only the program adds UDP from the standard library. For a microcontroller, build the
library for its target, for example --lib --target thumbv7em-none-eabihf with the Arm toolchain (bindgen then also
needs the toolchain's headers, in BINDGEN_EXTRA_CLANG_ARGS).
So far both ends were ours. ArduPilot's simulator (SITL) runs the real ArduCopter firmware on your computer, and
ardupilot_gcs/ is a small ground station in C for it, built from the import of the whole ardupilotmega.xml (every
message of chapter 3's dialect, not just two). Get a SITL build of ArduCopter for Linux from ArduPilot's firmware server
and its default parameters, and start it; it waits for a ground station on TCP port 5760:
curl -fLO https://firmware.ardupilot.org/Copter/stable/SITL_x86_64_linux_gnu/arducopter && chmod +x arducopter
curl -fLO https://raw.githubusercontent.com/ArduPilot/ardupilot/master/Tools/autotest/default_params/copter.parm
./arducopter --model quad --defaults copter.parm -I0 &Then import the dialect, build the ground station and run it:
cp -r wireforge-src/examples/tutorial/ardupilot_gcs .
wireforge import-mavlink "$DIALECTS/ardupilotmega.xml" ardupilot --name ardupilot
cmake -S ardupilot_gcs -B build/ardupilot_gcs -DARDUPILOT_PROJECT="$PWD/ardupilot" -DWireForge_DIR="$(wireforge cmake-dir)"
cmake --build build/ardupilot_gcs
build/ardupilot_gcs/ardupilot_gcs 15It sends a HEARTBEAT every second, asks for the telemetry streams, the AUTOPILOT_VERSION (with a COMMAND_LONG) and the parameter list, and counts what the autopilot sends back. With ArduCopter 4.7.2:
ardupilot_gcs: 2992 frames decoded, 0 rejected
ardupilot_gcs: HEARTBEAT 15 (type 2), ATTITUDE 59 (roll 0.001), GLOBAL_POSITION_INT 59, VFR_HUD 59 (alt 584.08)
ardupilot_gcs: AUTOPILOT_VERSION 1 (firmware 4.7.2), COMMAND_ACK 1 (command 512, result 0)
ardupilot_gcs: PARAM_VALUE 1369 of 1369
Every frame of the autopilot, of more than thirty kinds, is decoded and its checksum verified; none is rejected. The
handler has callbacks for seven messages, and the others are decoded and ignored. Stop the simulator with kill %1.
More: generated code (C++ and C), runtime, examples/cmake_consumer/.
If something goes wrong: Could not find a package configuration file provided by "WireForge": pass
-DWireForge_DIR="$(wireforge cmake-dir)". Port 14550 or 14551 in use: another ground station or simulator is running.
Next: 5. On a microcontroller