Crate postcard_rpc

The goal of postcard-rpc is to make it easier for a host PC to talk to a constrained device, like a microcontroller.

See the repo for examples

Architecture overview

                ┌──────────┐      ┌─────────┐         ┌───────────┐
                │ Endpoint │      │ Publish │         │ Subscribe │
                └──────────┘      └─────────┘         └───────────┘
                  │     ▲       message│                │        ▲
   ┌────────┐ rqst│     │resp          │       subscribe│        │messages
 ┌─┤ CLIENT ├─────┼─────┼──────────────┼────────────────┼────────┼──┐
 │ └────────┘     ▼     │              ▼                ▼        │  │
 │       ┌─────────────────────────────────────────────────────┐ │  │
 │       │                     HostClient                      │ │  │
 │       └─────────────────────────────────────────────────────┘ │  │
 │         │                  │              ▲           │       |  │
 │         │                  │              │           │       │  │
 │         │                  │              │           ▼       │  │
 │         │                  │      ┌──────────────┬──────────────┐│
 │         │                  └─────▶│ Pending Resp │ Subscription ││
 │         │                         └──────────────┴──────────────┘│
 │         │                                 ▲              ▲       │
 │         │                                 └───────┬──────┘       │
 │         ▼                                         │              │
 │      ┌────────────────────┐            ┌────────────────────┐    │
 │      ││ Task: out_worker  │            │  Task: in_worker  ▲│    │
 │      ├┼───────────────────┤            ├───────────────────┼┤    │
 │      │▼  Trait: WireTx    │            │   Trait: WireRx   ││    │
 └──────┴────────────────────┴────────────┴────────────────────┴────┘
                   │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ ▲
                   │   The Server + Client WireRx    │
                   │ │ and WireTx traits can be    │ │
                   │   impl'd for any wire           │
                   │ │ transport like USB, TCP,    │ │
                   │   I2C, UART, etc.               │
                   ▼ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
  ┌─────┬────────────────────┬────────────┬────────────────────┬─────┐
  │     ││  Trait: WireRx    │            │   Trait: WireTx   ▲│     │
  │     ├┼───────────────────┤            ├───────────────────┼┤     │
  │     ││      Server       │       ┌───▶│       Sender      ││     │
  │     ├┼───────────────────┤       │    └────────────────────┘     │
  │     │▼ Macro: Dispatch   │       │               ▲               │
  │     └────────────────────┘       │               │               │
  │    ┌─────────┐ │ ┌──────────┐    │ ┌───────────┐ │ ┌───────────┐ │
  │    │  Topic  │ │ │ Endpoint │    │ │ Publisher │ │ │ Publisher │ │
  │    │   fn    │◀┼▶│ async fn │────┤ │   Task    │─┼─│   Task    │ │
  │    │ Handler │ │ │ Handler  │    │ └───────────┘ │ └───────────┘ │
  │    └─────────┘ │ └──────────┘    │               │               │
  │    ┌─────────┐ │ ┌──────────┐    │ ┌───────────┐ │ ┌───────────┐ │
  │    │  Topic  │ │ │ Endpoint │    │ │ Publisher │ │ │ Publisher │ │
  │    │async fn │◀┴▶│   task   │────┘ │   Task    │─┴─│   Task    │ │
  │    │ Handler │   │ Handler  │      └───────────┘   └───────────┘ │
  │    └─────────┘   └──────────┘                                    │
  │ ┌────────┐                                                       │
  └─┤ SERVER ├───────────────────────────────────────────────────────┘
    └────────┘

Defining a schema

Typically, you will define your “wire types” in a shared schema crate. This crate essentially defines the protocol used between two or more devices.

A schema consists of a couple of necessary items:

Wire types

We will need to define all of the types that we will use within our protocol. We specify normal Rust types, which will need to implement or derive three important traits:

• serde’s Serialize trait - which defines how we can convert a type into bytes on the wire
• serde’s Deserialize trait - which defines how we can convert bytes on the wire into a type
• postcard_schema’s Schema trait - which generates a reflection-style schema value for a given type.

Endpoints

Now that we have some basic types that will be used on the wire, we need to start building our protocol. The first thing we can build are Endpoints, which represent a bidirectional “Request”/“Response” relationship. One of our devices will act as a Client (who makes a request, and receives a response), and the other device will act as a Server (who receives a request, and sends a response). Every request should be followed (eventually) by exactly one response.

An endpoint consists of:

• The type of the Request
• The type of the Response
• A string “path”, like an HTTP URI that uniquely identifies the endpoint.

Topics

Sometimes, you would just like to send data in a single direction, with no response. This could be for reasons like asynchronous logging, blindly sending sensor data periodically, or any other reason you can think of.

Topics have no “client” or “server” role, either device may decide to send a message on a given topic.

A topic consists of:

• The type of the Message
• A string “path”, like an HTTP URI that uniquely identifies the topic.

Modules

• accumulator
  Accumulator tools
• hash
  URI and Schema Hashing
• header
  Postcard-RPC Header Format
• host_client
  A postcard-rpc host client
• server
  Definitions of a postcard-rpc Server
• standard_icd
  These are items you can use for your error path and error key.
• test_utils
  Test utilities for doctests and integration tests
• uniques
  Create unique type lists at compile time

Macros

• define_dispatch
  Define Dispatch Macro
• endpoint
  Endpoint macro
• endpoints
  Endpoints macro
• merge_unique_types
  merge_unique_types collects all unique, non-primitive types contained by the given comma separated types. It can be used with any types that implement the Schema trait, and returns a &'static [&'static NamedType].
• topic
  Topic macro
• topics
  Topics macro
• unique_types
  unique_types collects all unique, non-primitive types contained by the given single type. It can be used with any type that implements the Schema trait, and returns a &'static [&'static NamedType].

Structs

• DeviceMap
  An overview of all topics (in and out) and endpoints
• EndpointMap
  An overview of a list of endpoints
• Key
  The Key uniquely identifies what “kind” of message this is.
• Key1
  A compacted 2-byte key
• Key2
  A compacted 2-byte key
• Key4
  A compacted 4-byte key
• TopicMap
  An overview of a list of topics

Traits

• Endpoint
  A marker trait denoting a single endpoint
• Topic
  A marker trait denoting a single topic