Skip to main content
Version: 2.7.0-beta 🚧

Object dictionary

An object dictionary (OD) allows various developers of different services to make them interoperate regardless of the units they use on their code.

Example: If my_service1 uses an angle in radians and my_service2 uses degrees, what is the unit they should use to share the angle information?

An object dictionary defines a set of typical objects that can be transmitted through Luos messages. It allows to send these objects with a unit and to use it in any other units, in other services.

Luos engine defines objects based on physical values following the SI standard.

Objects and types​

Each object in the Object Dictionary has a specific Type. For example:

// Define object angular_position as an angular_position_t type
angular_position_t angular_position;

You can create your variables using these objects but never set OD variables directly with a value. Instead, you have to use functions available on the Luos engine's OD:

// Set object angular_position
float deg = 12.0;
angular_position_t angular_position = AngularOD_PositionFrom_deg(deg);

Following this rule, everybody will be able to use your values.

All the types are listed in the table summary at the end of this page.

Conversions​

As many units exist, many conversion functions are available. As a result, they follow logic naming rules in order to quickly find the desired function without having to search for it.

Unit conversions​

There are two types of unit conversion: in one way (OD type from the desired unit), and in the other way (OD type to the desired unit):

  • from conversion: Converts a value with a defined unit into a desired OD data.

Format: [type_var] = [type]From_[unit]([value])

// save a linear_position from a mm value
linear_position_t linear_position = LinearOD_PositionFrom_mm(float mm);
  • to conversion: Converts an OD data into a specific unit.

Format: [value] = [type]To_[unit]([type_var])

// convert the variable linear_position into mm
float mm = LinearOD_PositionTo_mm(linear_position_t linear_position);

Messages conversions​

In the same way, both conversions are available for messages (OD type from message and OD type to message):

  • from conversion: Gets a OD data from a message.

Format: [type]FromMsg([type_var], msg)

// get the linear_position from the message msg
void LinearOD_PositionFromMsg(linear_position_t* linear_position, msg_t* msg);
  • to conversion: Inserts a desired OD data into a message.

Format: [type]ToMsg(type_var], msg)

// insert the linear_position into the message msg
void LinearOD_PositionToMsg(linear_position_t* linear_position, msg_t* msg);

Types and units table summary​

Here are listed the existing types:

TypeAvailable prefix and other units
linear_positionnm, μm, mm, cm, m, km, in, ft, mi
linear_speedmm/s, m/s, km/h, in/s, mi/h
angular_positiondeg, revolution, rad
angular_speeddeg/s, revolution/s, revolution/min, rad/s
forceN, kgf, ozf, lbf
momentN.mm, N.cm, N.m, kgf.mm, kgf.cm, kgf.m, ozf.in, lbf.in
voltagemV, V
currentmA, A
powermW, W
ratiopercentage
temperaturedeg_c, deg_f, deg_k
color8bit_RGB unsigned char [3]
controlcontrol_t (play, pause, stop, record)
pidasserv_pid_t float [3] {proportional, integral, derivative}
tip

To find out what conversion function to use if you don't know it, replace the characters / or . in the units by the character _. The character µ is replaced by u, and revolution is replaced by rev.

Examples:
convert a linear speed to mm/s: LinearOD_SpeedTo_mm_s();
convert a value in μm to a linear position: LinearOD_PositionFrom_um();
convert a value in revolutions/s to an angular speed: AngularOD_SpeedFrom_rev_s();

A feedback? Let's discuss on Discord | Github