Loading [MathJax]/jax/output/HTML-CSS/config.js
upkie 6.1.0
Open-source wheeled biped robots
All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
upkie::cpp::spine::Spine Class Reference

Loop transmitting actions to the actuation and observations to the agent. More...

#include <Spine.h>

Classes

struct  Parameters
 Spine parameters. More...
 

Public Member Functions

 Spine (const Parameters &params, actuation::Interface &interface, ObserverPipeline &observers)
 Initialize spine. More...
 
void reset (const palimpsest::Dictionary &config)
 Reset the spine with a new configuration. More...
 
void run ()
 Run the spine loop until termination. More...
 
void cycle ()
 Spin one cycle of the spine loop.
 
void simulate (unsigned nb_substeps)
 Alternative to run where the actuation interface is cycled a fixed number of times, and communication cycles are not frequency-regulated. More...
 
void cycle_actuation ()
 Spin one cycle of communications with the actuation interface. More...
 

Protected Attributes

const unsigned frequency_
 Frequency of the spine loop in [Hz].
 
actuation::Interfaceactuation_
 Interface that communicates with actuators. More...
 
AgentInterface agent_interface_
 Shared memory mapping for inter-process communication.
 
std::future< Output > actuation_output_
 Future used to wait for moteus replies.
 
std::vector< ServoReply > servo_replies_
 Latest servo replies. They are copied and thread-safe.
 
palimpsest::Dictionary working_dict_
 All data from observation to action goes to this dictionary.
 
ObserverPipeline observer_pipeline_
 Pipeline of observers, executed in that order.
 
mpacklog::Logger logger_
 Logger for the working_dict_ produced at each cycle.
 
std::vector< char > ipc_buffer_
 Buffer used to serialize/deserialize dictionaries in IPC.
 
const bool & caught_interrupt_
 Boolean flag that becomes true when an interruption is caught.
 
StateMachine state_machine_
 Internal state machine.
 
State state_cycle_beginning_
 State after the last Event::kCycleBeginning.
 
State state_cycle_end_
 State after the last Event::kCycleEnd.
 
size_t rx_count_
 Number of actuation replies received during the latest cycle.
 

Detailed Description

Loop transmitting actions to the actuation and observations to the agent.

The spine acts as the intermediary between the actuation interface (e.g. moteus servos connected to the CAN-FD bus) and an agent communicating over shared memory (the agent interface). It packs observations to the agent from actuation replies and commands to the actuation from agent actions.

The spine processes requests at the beginning and end of each control cycle according to its StateMachine. The overall specification of the state machine is summarized in the following diagram:

See StateMachine for more details.

Constructor & Destructor Documentation

◆ Spine()

upkie::cpp::spine::Spine::Spine ( const Parameters params,
actuation::Interface interface,
ObserverPipeline observers 
)

Initialize spine.

Parameters
[in]paramsSpine parameters.
[in,out]interfaceInterface to actuators.
[in,out]observersPipeline of observers to run, in that order, at each cycle.

Member Function Documentation

◆ cycle_actuation()

void upkie::cpp::spine::Spine::cycle_actuation ( )

Spin one cycle of communications with the actuation interface.

A cycle consists in:

  1. Run the observer pipeline over the latest reply
  2. Prepare servo commands
  3. Wait to receive the reply from the previous cycle over the interface
  4. If applicable, start the next cycle:

◆ reset()

void upkie::cpp::spine::Spine::reset ( const palimpsest::Dictionary &  config)

Reset the spine with a new configuration.

Parameters
[in]configNew configuration dictionary forwarded to spine modules (actuation interface, observers).

◆ run()

void upkie::cpp::spine::Spine::run ( )

Run the spine loop until termination.

Each iteration of the loop runs observers, computes the action and cycles the actuation interface. Additionally, this function collects debug values and logs everything.

Note
The spine will catch keyboard interrupts once this function is called.

◆ simulate()

void upkie::cpp::spine::Spine::simulate ( unsigned  nb_substeps)

Alternative to run where the actuation interface is cycled a fixed number of times, and communication cycles are not frequency-regulated.

Parameters
[in]nb_substepsNumber of actuation cycles per action.

Thus function assumes the agent alternates acting and observing. Simulation steps are triggered at startup (to construct the initial observation) and at each action request.

Note
As its name suggests, do not use this function on a real robot.

Note that there is currently a delay of three substeps between observation and simulation. That is, the internal simulation state is always three substeps ahead compared to the values written to the observation dictionary when cycling the actuation. This decision is discussed in https://github.com/orgs/upkie/discussions/238#discussioncomment-8984290

Member Data Documentation

◆ actuation_

actuation::Interface& upkie::cpp::spine::Spine::actuation_
protected

Interface that communicates with actuators.

The actuation interface communicates over the CAN-FD bus on real robots. Otherwise, it can be for instance a mock or a simulator interface.


The documentation for this class was generated from the following files: