Appendix B: Command reference

Every command id, its arguments, the robots that act on it, and its status.

Command ids share one numbering space across every robot type, so an id is only ever implemented by some of them, and sending one to a robot that does not implement it is ignored exactly like sending an id that does not exist. Nothing on this wire is acknowledged: the state stream's actuator echo is the only receipt. In the Status column, live means a robot type acts on the id today, not yet means it is on the wire and no robot acts on it, and absent means the robot type it belongs to is not in the simulator. The constants live in vrobots_sdk::cmd, and cmd::name(id) maps a value back to its constant name for logging, returning "" for an unknown id.

Command ids

Where the CmdArgs field says "not documented", the SDK ships no typed method for that id and the source does not name the field it reads, so the payload shape has to come from the simulator before you build on it. The units given for those ids follow from the SDK's everything-is-SI rule and the constant's name rather than from a statement in the source.

The CmdArgs field for SET_ANGVEL is vec3, verifiable from both ends: set_angvel builds CmdArgs::vector(rates), and on the way back subscribe_command yields a Setpoint only for commands carrying a vec3, with subscribe_setpoint as shorthand for subscribe_command(cmd::SET_ANGVEL).

Not yet. Seventeen ids above are carried by the schema and acted on by nothing. They publish without error and the state stream does not change, which is indistinguishable from a wrong sys_id or a wrong array length. Commands nothing acts on shows what that looks like from the outside.

Fixed wing mode constants

These are i32 values carried in CmdArgs::int_val, not command ids. They select the behaviour of SET_FW_CTRL_MODE and SET_FW_EST_SOURCE.

reset() returns both settings to their defaults, deliberately: direct surface control with zeroed latches would relaunch the aircraft unflyable. A direct-surface client re-asserts both after every reset.

The CmdArgs shape

Every command carries the same argument struct, and each id reads the one or two fields it cares about.

#![allow(unused)]
fn main() {
#[non_exhaustive]
pub struct CmdArgs {
    pub int_val: i32,
    pub float_val: f64,
    pub int_arr: Vec<i32>,
    pub float_arr: Vec<f64>,
    pub vec3: Option<[f64; 3]>,
    pub vec4: Option<[f64; 4]>,   // [x, y, z, w]
    pub vec3_arr: Vec<[f64; 3]>,
    pub vec4_arr: Vec<[f64; 4]>,
}
}

typedef struct vrsdk_cmd_args_t {
    int32_t int_val;
    double float_val;
    const int32_t *int_arr;
    size_t int_arr_len;
    const double *float_arr;
    size_t float_arr_len;
    const double *vec3;
    const double *vec4;
    const double *vec3_arr;
    size_t vec3_arr_len;
    const double *vec4_arr;
    size_t vec4_arr_len;
} vrsdk_cmd_args_t;

int_val: int = 0
float_val: float = 0.0
int_arr: Optional[Sequence[int]] = None
float_arr: Optional[Sequence[float]] = None
vec3: Optional[Sequence[float]] = None
vec4: Optional[Sequence[float]] = None
vec3_arr: Optional[Sequence[Sequence[float]]] = None
vec4_arr: Optional[Sequence[Sequence[float]]] = None

The same eight fields carry the same meanings in all three. C++ uses the C struct directly, so every array is a pointer with an explicit _len, and vec3_arr and vec4_arr are flat double arrays whose length counts vectors rather than doubles. Python has no argument type at all: the eight are keyword arguments of send_cmd.

The struct is #[non_exhaustive], so it cannot be built with a struct literal. Build it from CmdArgs::default() plus chained setters, or from a shorthand.

Each with_* setter consumes self and is #[must_use], so they chain. Empty vectors and None are omitted from the wire entirely rather than sent at zero length. Floats narrow: f64 in the API, f32 on the wire.

VirtualRobot::send_cmd(&self, cmd_id: u32, args: &CmdArgs) -> VrResult<()> is the escape hatch for an id with no typed method. It returns Deleted if the robot has been deleted and Publish if zenoh refuses the put, and nothing else: it cannot tell you whether any robot acted on the id.

Next: Appendix C: Error reference

See also: The generic command, Commands latch