Crate pk_command 

PK Command

A lightweight, reliable data transfer protocol designed for constrained channels (e.g., HID, Serial) between a Host and an Embedded Device.

Key Features

• Reliability: Built-in ACK/Retransmission mechanism.
• Efficiency: Fixed-length headers and data slicing for small MTUs.
• Flexibility: Supports variable access (GET/SET) and remote method invocation (INVOK).
• no_std Support: Core logic is compatible with embedded systems without an OS. Note that alloc is still used in no_std environments.
• Wait Mechanism: Keep-alive AWAIT packets for long-running operations.

Architecture

The protocol operates using Transaction Chains. A chain starts with a START command and ends with ENDTR. Large payloads are automatically sliced into SDATA packets.

Command Format

Every command follows the fixed layout:

[MSG ID][OPERATION NAME] [OBJECT] [DATA].

• MSG ID: A base-94 encoded unsigned integer (using ASCII characters from ‘!’ to ‘~’) that uniquely identifies the command within a transaction.
• OPERATION NAME: A 5-character ASCII string representing the command type. All the operations defined in the specification are defined in this library. (See types::Operation for details.)
• OBJECT: An optional 5-character ASCII string that provides additional context for the operation (e.g., variable name, method name).
• DATA: An optional binary payload that carries parameters or return values. It can be of arbitrary length and may contain any byte values.

See Command for a structured representation of commands and utilities for parsing and serialization.

Note that:

• OBJECT is either omitted, or exactly 5 ASCII characters.
• DATA (payload) is arbitrary binary data.
• The total length of a command is limited by the transportation layer’s MTU (e.g., 64 bytes for HID). (See PkCommandConfig.) But the protocol handles slicing and reassembly of large payloads automatically, so you can work with large data without worrying about the underlying transport constraints.

Example

use pk_command::{PkCommand, PkCommandConfig, PkHashmapMethod, PkHashmapVariable};

// 1. Setup configuration and accessors
let config = PkCommandConfig::default(64);
let vars = PkHashmapVariable::new(vec![]);
let methods = PkHashmapMethod::new(vec![]);

// 2. Initialize the state machine
let pk = PkCommand::<_, _, std::time::Instant>::new(config, vars, methods);

// 3. Basic loop driving the protocol
loop {
    // Handle received bytes from your transport (HID/Serial/etc.)
    if let Some(bytes) = transport.recv() {
        pk.incoming_command(bytes);
    }

    // Process and get commands to send back
    if let Some(cmd) = pk.poll() {
        transport.send(cmd.to_bytes());
    }

    if pk.is_complete() {
        break;
    }
}

Feature flags

• std: Enables features that require the Rust standard library. (Mainly the convenient wrappers like PkPromise, PkHashmapVariable, PkHashmapMethod) Enabled by default.
• embassy: Enables integration with the Embassy async framework. Flags below are also enabled when this is active:
  • embassy-time: Enables the support for embassy-time crate, which provides timekeeping utilities for embedded environments.
  • embassy-runtime: Enables the support for embassy-executor crate, which provides integration between the main state machine and Embassy async tasks.
• tokio-runtime: Enables integration with the Tokio async runtime. Provides tokio_adapter for running async operations within method implementations. Requires std feature.
• smol-runtime: Enables integration with the Smol async executor. Provides smol_adapter for running async operations within method implementations. Requires std feature.

Modules

embassy_adapterembassy-runtime

Embassy runtime adapters.

msg_idstd

Module for handling PK Command Message IDs.

smol_adapterstd and smol-runtime

Smol runtime adapters.

tokio_adapterstd and tokio-runtime

Tokio runtime adapters.

types

Core data structures and types for PK Command.

Macros

embassy_method_accessorembassy-runtime

Helper macro for creating a PkMethodAccessor backed by Embassy tasks.

Structs

EmbassyInstantembassy-time

A PkInstant adapter for embassy_time::Instant.

PkCommand

The main state machine for handling the PK Command protocol.

PkCommandConfig

Configuration for the PkCommand state machine.

PkHashmapMethodstd

A wrapper for std::collections::HashMap that implements the PkMethodAccessor trait.

PkHashmapVariablestd

A wrapper for std::collections::HashMap that implements the PkVariableAccessor trait.

PkPromisestd

A simple implementation of Pollable that executes tasks in a background thread.

Traits

PkInstant

Trait representing an instant in time.

PkMethodAccessor

Trait defining how to invoke methods by their string key.

PkVariableAccessor

Trait defining how to access (get/set) variables by their string key.

Pollable

A handle for a long-running operation that can be polled for completion.