Crate esp_hosted

Source
Expand description

§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 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.
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
PayloadHeader
Adapted from esp-hosted-mcu/common/esp_hosted_header.h This is at the start of the message, and is followed by the RPC header. See ESP-hosted-MCU readme, section 7.1.
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
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§

build_frame_ble
Public, since the BLE interface is more raw, relying on HCI from the host.
cfg_heartbeat
Minimum of 10s.
parse_msg
Parse the payload header, and separate the RPC bytes from the whole message. Accepts the whole message received.
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.