upkie::cpp::spine Namespace Reference

Inter-process communication protocol with the spine. More...

Classes
class	AgentInterface
	Memory map to shared memory. More...
class	Spine
	Loop transmitting actions to the actuation and observations to the agent. More...
class	StateMachine
	Spine state machine. More...

Enumerations
enum class	Request : uint32_t {   kNone = 0 , kAction = 1 , kStart = 2 , kStop = 3 ,   kError = 4 }
	Request flag used for shared-memory inter-process communication. More...
enum class	State : uint32_t {   kSendStops = 0 , kReset = 1 , kIdle = 2 , kStep = 3 ,   kShutdown = 4 , kOver = 5 }
	States of the state machine. More...
enum class	Event : uint32_t { kCycleBeginning = 0 , kCycleEnd = 1 , kInterrupt = 2 }
	Events that may trigger transitions between states. More...

Functions
void	allocate_file (int file_descriptor, int bytes)
	Allocate file with some error handling. More...
constexpr const char *	state_name (const State &state) noexcept
	Name of a state. More...

Variables
constexpr size_t	kMebibytes = 1 << 20
	Number of bits in one mebibyte.
constexpr unsigned	kNbStopCycles = 5
	When sending stop cycles, send at least that many.

Detailed Description

Inter-process communication protocol with the spine.

Main control loop between agents and actuators.

Design notes: one alternative was a proper FSM with a clear distinction between states (what the spine is doing) and transitions (agent requests, spine replies, etc.). This could have allowed more granularity, such as the spine doing nothing (instead of sending stops) when it is idle, however at the cost of more complexity. We choose to go for the simpler (riskier) version where both agent and spine directly manipulate the agenda.

Enumeration Type Documentation

Event

enum class upkie::cpp::spine::Event : uint32_t

strong

Events that may trigger transitions between states.

Enumerator
kCycleBeginning	Beginning of a spine cycle.
kCycleEnd	End of a spine cycle.
kInterrupt	Caught an interruption signal.

Request

enum class upkie::cpp::spine::Request : uint32_t

strong

Request flag used for shared-memory inter-process communication.

Enumerator
kNone	Flag set when there is no active request.
kAction	Flag set to indicate an action has been supplied.
kStart	Flag set to start the spine.
kStop	Flag set to stop the spine.
kError	Flag set when the last request was invalid.

State

enum class upkie::cpp::spine::State : uint32_t

strong

States of the state machine.

Enumerator
kSendStops	Send stop commands to all actuators.
kReset	Reset all configured modules.
kIdle	Do nothing.
kStep	Read a new action from shared memory.
kShutdown	Shut down the spine.
kOver	Final termination.

Function Documentation

allocate_file()

void upkie::cpp::spine::allocate_file	(	int	file_descriptor,
		int	bytes
	)

Allocate file with some error handling.

Parameters

[in]	file_descriptor	File descriptor.
[in]	bytes	Number of bytes to allocate.

state_name()

constexpr const char * upkie::cpp::spine::state_name ( const State &  state )

constexprnoexcept

Name of a state.

Parameters

[in]

state

State to name.