Crate esp_hosted 

ESP Hosted

For connecting to an ESP-Hosted-MCU from a Host MCU with firmware written in rust.

Compatible with ESP-Hosted-MCU 2.0.6 and ESP IDF 5.4.1 (And likely anything newer), and any host MCU and architecture. For details on ESP-HOSTED-MCU’s protocol see this document. For how to use the commands in the library effectively, reference the ESP32 IDF API docs

This library includes two approaches: A high-level API using data structures from this library, and full access to the native protobuf structures. The native API is easier to work with, but only implements a small portion of functionality. The protobuf API is complete, but more cumbersome.

This library does not use an allocator. This makes integrating it simple, but it uses a significant amount of flash for static buffers. These are configured in the build_proto/src/main.rs script on a field-by-field basis.

It’s transport agnostic; compatible with SPI, SDIO, and UART. It does this by allowing the application firmware to pass a generic write function, and reads are performed as functions that act on buffers passed by the firmware.

Re-exports

pub use header::PayloadHeader;

pub use header::build_frame_ble;

pub use proto::Rpc as RpcP;

pub use proto::RpcId as RpcIdP;

pub use proto::RpcType as RpcTypeP;

pub use proto_data::RpcId;

pub use crate::proto_data::RpcId;

Modules

ble

Minimal HCI support for Bluetooth operations.

header

This module contains the payload header and TLV structure which proceeds RPC data, creating a frame, and support types.

proto

proto_data

Contains data types specific to the ESP-Hosted-MCU proto buffer. This contains definitions for the data types [de]serialized. They’re not automatically generated from the .proto file, and are used in our higher-level API.

wifi

This module contains Wi-Fi and BLE-specific functionality.

Macros

copy_le

parse_le

Structs

HciMsg

Rpc

See esp_hosted_rpc.proto.

WifiMsg

Enums

EspCode

ESP-IDF error codes mapped to a u16.

EspError

A simple error enum for our host-side protocol

MsgParsed

PacketType

RpcPayload

RpcType

See esp_hosted_rpc.proto, enum by this name. And esp_hosted_rpc.pb-c.h. (Maybe taken from there?) We encode this as a varint.

WireType

https://protobuf.dev/programming-guides/encoding/

Functions

cfg_heartbeat

Minimum of 10s.

parse_msg_header_not_read

Parse the payload with header, and separate the RPC bytes from the whole message. Accepts the whole message received.

parse_msg_header_read

Use this for SPI, after parsing the header in the first 12-byte transaction. Assumes the header has been read already, and passed as a param.

setup_rpc

Sets up an RPC command to write. This makes calls to set up payload header and TLV. returns the total payload size after setup. (Including PL header, TLV, RPC). This function is mainly used internally by our higher-level API.

setup_rpc_proto

Sets up an RPC command to write using the automatic protbuf decoding from micropb. This is flexible, and allows writing arbitrary commands, but its interface isn’t as streamlined as our native impl.

write_rpc_proto

Write an automatically-decoded protobuf message directly.