Echo Services

This section documents the concrete Echo services that ship with the Embedded Infrastructure Library and closely related products. The Echo Protocol page describes the underlying protocol, encoding rules, and message conventions. The pages below describe individual services, their responsibilities, allowed states, message flows, and typical interaction patterns.

Each service is defined in a .proto file, exposes a set of RPC methods, and is paired with a matching response service that carries the asynchronous callbacks.

Definition of terms

Vocabulary used consistently throughout this section, on all pages and in every sequence diagram.

App

The application code that consumes the Echo API by invoking methods and observing callbacks. The App runs on a phone, another MCU, or another host, and communicates with the Node over the Echo transport.

Node

The endpoint that implements the Echo service on the device side. This is the component that talks BLE (or another transport) with the peer, exposes the Echo methods over the RPC surface, and emits the asynchronous callbacks. In role-agnostic diagrams the participant is labelled Node. In dual-role diagrams both endpoints appear as Peripheral Node and Central Node to distinguish them.

BLE Peripheral / BLE Central

Peer BLE devices the Node interacts with. These are drawn as separate lifelines on diagrams that make link-layer events explicit. They are not something the App drives directly - the App observes their effects only through Echo callbacks (typically CurrentState, DeviceDiscovered, PairingResult, etc.).

Service Structure

An Echo service definition consists of:

  • A request service (e.g. GapCentral) that lists the RPC methods a caller can invoke.

  • A response service (e.g. GapCentralResponse) that lists the asynchronous callbacks the caller receives.

  • Optionally a readiness service used during startup handshakes.

Every service has a unique service_id, and every RPC method within a service has a unique method_id. Both are encoded on the wire as described in Echo Protocol.

Each service page documents:

  • The interface (class diagram).

  • State constraints, callback constraints, and startup handshake.

  • One sequence diagram per RPC method.

  • Cross-service and end-to-end sequences that illustrate typical flows.

  • Concrete examples with real values where useful.

Available Services

If you are new to these docs, start with BLE End-to-End Flows to see how the pieces fit together. For a specific API, jump straight to the matching service page above.

Contract vs. configuration

Each service’s .proto file codifies a stack-agnostic contract, derived from the underlying standard (the Bluetooth Core Specification for BLE services). The contract fixes what must happen: which methods exist, what messages they carry, in what order responses arrive, and which states each is valid in.

Concrete implementations of the contract live in the vendor-specific stacks. Each stack satisfies the contract independently. Where these docs say a behaviour is "stack-dependent", for example the exact moment CurrentState(connected) fires, that is not a hedge but a deliberate reflection of the architecture: the contract guarantees the outcome, the stack chooses the timing.

Read the diagrams with this split in mind:

  • Arrows between App and Node are the Echo API contract. Every implementation must honour these.

  • Arrows between Node and the peer BLE device are protocol events required by the standard, and are contract-level too.

  • Prose notes flag where implementations legitimately differ within that contract.

Conventions

Unless a service’s page overrides them, the following conventions apply:

  • All methods are asynchronous. Callbacks are delivered on the paired response service.

  • A service is only available after its startup handshake completes (typically the first CurrentState callback).

  • Calling a method outside its allowed states results in an assertion.

  • When a callback is specified for a method, another call of the same method is not allowed until the callback has been received.

  • Deprecated methods and services are marked as such and will be removed in a future release.