Communication Classes

These classes implement communication with the motion, perception, and speech sockets. The Robot class handles all connections at once, and is probably the one you should use. The separate base classes should really only be used in cases where you have restricted access to sockets.

All communication classes are meant to be used as context managers (inside a with block) and will raise exceptions if not.

class navel.Robot

Bases: Motion, Perception, Speech

Send commands and receive data from robot.

This class can be used to send motion or speech commands, register callbacks for bookmarks, fetch the latest perception data, and set robot configuration values. It should always be used as a context manager (inside a with block).

clear_persist(uid: int)

Sends a message to robot to remove person from persistent storage.

Parameters:

uid (int) – Unique identifier of person.

Raises:

• ValueError – When uid is outside limits.

• SocketError – In cases where message cannot be sent via socket.

config_set(name, value, valType)

Sends a message to change the value of a config field.

Parameters:

• name (str) – Name of config field to set. Parameters can be explored in browser interface. Concatenate name segments from there, e.g. “rndr_rgbsensor_max_brightness”.

• value (int or float) – Value to set.

• valType (DataType) – DataType Enum describing value datatype.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_eyelids(openness_l: float, openness_r: float)

Sends a message setting how open the eyes should be.

Parameters:

• openness_l (float) – Scalar value of how open left eye should be, where 1 is open and 0 is closed.

• openness_r (float) – Scalar value of how open right eye should be, where 1 is open and 0 is closed.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_facial_expression(neutral: float = 0, happy: float = 0, sad: float = 0, surprise: float = 0, anger: float = 0, smile: float = 0)

Sends a message setting the facial expression of the robot.

This function sets the magnitude of each of the robots five expressions. Each argument contains a scalar value of how extreme the argument emotion is, where emotion max is 1 and emotion minimum is 0.

Parameters:

• neutral (float) – Sets magnitude of neutral expression.

• happy (float) – Sets magnitude of happy expression.

• sad (float) – Sets magnitude of sad expression.

• surprise (float) – Sets magnitude of surprise expression.

• anger (float) – Sets magnitude of anger expression.

• smile (float) – Sets magnitude of smile expression.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_mouth(openness: float)

Sends a message setting how wide the mouth should be open.

Parameters:

openness (float) – Scalar value which controls how wide mouth should be open, 1 = open, 0 = closed.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_overlay(overlay: Bryan)

Sends a message rotating the head from its natural position (which

is determined by the direction of focus) using Tait-Bryan angles.

Parameters:

overlay (Bryan) – Tait-Bryan angles describing offset from natural position.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_path_limits(v_max: float, a_max: float, j_max: float)

Sends pathplanner limits for head motion to robot.

Parameters:

• v_max (float) – Maximum velocity.

• a_max (float) – Maximum acceleration.

• j_max (float) – Maximum jerk.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_cart(cart: CartSys3d, head: float)

Sends a message for robot to look at a point in space.

Parameters:

• cart (CartSys3d) – 3d target point to look at.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_person(uid: int, head: float)

Sends a message setting which person robot should look at.

Parameters:

• uid (int) – Unique identifier of person.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_px(px: Point2d, head: float)

Sends a message to robot to look at a pixel.

Parameters:

• px (Point2d) – 2d point on the image plane.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

move_and_rotate_base(distance: float, angle: float, speed: float | None = None, acceleration: float | None = None)

Sends both a move and a rotate command to robot.

Command translates the robot forward/backward by the desired distance and rotates it around Z axis by desired angle. If no speed/acceleration are defined, the maximum will be used. Rotational speed is calculated to match movement speed.

Warning: rotation amount is likely to be inaccurate, some trial and error may be necessary to define wanted movements.

Parameters:

• distance (float) – Motion magnitude and direction in meters.

• angle (float) – Rotation magnitude and direction in degrees.

• speed (float) – Desired peak movement speed (m/s).

• acceleration (float) – Desired peak acceleration (m/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

move_base(distance: float, speed: float | None = None, acceleration: float | None = None)

Sends a move command to robot.

Command translates the robot forward/backward by desired distance. If no speed/acceleration are defined, the maximum will be used.

Parameters:

• distance (float) – Motion magnitude and direction in meters.

• speed (float) – Desired peak speed (m/s).

• acceleration (float) – Desired peak acceleration (m/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

next_frame(timeout: float = 1) → Awaitable[PerceptionData]

Receives next frame of perception data from the robot.

Will always return the newest available frame, which may be from slightly before the function was called, but never a duplicate. In general, frames should arrive roughly every 0.1s.

Parameters:

timeout (float, optional) – Maximum time to wait for a frame in seconds. Defaults to 1.

Raises:

• ConnectionAbortedError – If socket connection is lost

• TimeoutError – If timeout is triggered.

Returns:

The received perception data.

Return type:

Awaitable[PerceptionData]

rotate_arms(left_angle: float, right_angle: float)

Sends rotate arms command to robot.

The arm motion is limited in the upper back and arms can not do a full rotation. Rotation is around robot’s -Y axis, 0 is straight down, positive is generally up and negative is generally down.

Parameters:

• angle_l (float) – Absolute rotation of left arm in degrees.

• angle_r (float) – Absolute rotation of right arm, in degrees.

Raises:

SocketError – In cases where message cannot be sent via socket.

rotate_base(angle: float, speed: float | None = None, acceleration: float | None = None)

Sends a rotate command to robot.

Command rotates the robot around Z axis by desired angle. If no speed/acceleration are defined, the maximum will be used.

Parameters:

• angle (float) – Rotation magnitude and direction in degrees.

• speed (float) – Desired peak speed (deg/s).

• acceleration (float) – Desired peak acceleration (deg/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

say(text: str)

Sends a speech text message to speech socket. If the message is too long, it may be split up and sent as parts.

Parameters:

text (str) – contents of message to be sent to speech socket.

Raises:

• TypeError – If text is not string

• SocketError – If errors connecting to socket or sending message

set_bookmark_callback(bookmark: int, action: Callable[[SpeechMessenger], Awaitable]) → None

Sets a callback for the given bookmark number.

Parameters:

• bookmark (int) – Bookmark number to bind this action to.

• action (callable) – Function that should be called. Must be async and take a reference to this object as its only parameter

set_persist(uid: int)

Sends a message to robot to add person to persistent storage.

Parameters:

uid (int) – Unique identifier of person.

Raises:

• ValueError – When uid is outside limits.

• SocketError – In cases where message cannot be sent via socket.

tilt_base(x_percent: float, y_percent: float)

Sends tilt body command to robot.

Parameters:

• x (float) – Tilt around X axis as a fraction of maximum. -1 (left) to 1 (right).

• y (float) – Tilt around Y axis as a fraction of maximum. -1 (backwards) to 1 (forwards).

Raises:

SocketError – In cases where message cannot be sent via socket.

property volume: int

The current volume of the robot speakers.

class navel.Motion(socket_name='/run/bodyd/motion.sock')

Bases: MotionMessenger

Send messages to motion socket.

This class is able to send protobuf messages via a unix domain socket (UDS). As soon as the object is created it will attempt to connect to the socket. If socket connection is successful, methods can be used to send messages. Each message is converted to a protobuf format before being sent to the motion socket.

Parameters:

socket_name (str) – Name of motion socket to connect too.

config_set(name, value, valType)

Sends a message to change the value of a config field.

Parameters:

• name (str) – Name of config field to set. Parameters can be explored in browser interface. Concatenate name segments from there, e.g. “rndr_rgbsensor_max_brightness”.

• value (int or float) – Value to set.

• valType (DataType) – DataType Enum describing value datatype.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_eyelids(openness_l: float, openness_r: float)

Sends a message setting how open the eyes should be.

Parameters:

• openness_l (float) – Scalar value of how open left eye should be, where 1 is open and 0 is closed.

• openness_r (float) – Scalar value of how open right eye should be, where 1 is open and 0 is closed.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_facial_expression(neutral: float = 0, happy: float = 0, sad: float = 0, surprise: float = 0, anger: float = 0, smile: float = 0)

Sends a message setting the facial expression of the robot.

This function sets the magnitude of each of the robots five expressions. Each argument contains a scalar value of how extreme the argument emotion is, where emotion max is 1 and emotion minimum is 0.

Parameters:

• neutral (float) – Sets magnitude of neutral expression.

• happy (float) – Sets magnitude of happy expression.

• sad (float) – Sets magnitude of sad expression.

• surprise (float) – Sets magnitude of surprise expression.

• anger (float) – Sets magnitude of anger expression.

• smile (float) – Sets magnitude of smile expression.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_mouth(openness: float)

Sends a message setting how wide the mouth should be open.

Parameters:

openness (float) – Scalar value which controls how wide mouth should be open, 1 = open, 0 = closed.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_overlay(overlay: Bryan)

Sends a message rotating the head from its natural position (which

is determined by the direction of focus) using Tait-Bryan angles.

Parameters:

overlay (Bryan) – Tait-Bryan angles describing offset from natural position.

Raises:

SocketError – In cases where message cannot be sent via socket.

head_path_limits(v_max: float, a_max: float, j_max: float)

Sends pathplanner limits for head motion to robot.

Parameters:

• v_max (float) – Maximum velocity.

• a_max (float) – Maximum acceleration.

• j_max (float) – Maximum jerk.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_cart(cart: CartSys3d, head: float)

Sends a message for robot to look at a point in space.

Parameters:

• cart (CartSys3d) – 3d target point to look at.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_person(uid: int, head: float)

Sends a message setting which person robot should look at.

Parameters:

• uid (int) – Unique identifier of person.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

look_at_px(px: Point2d, head: float)

Sends a message to robot to look at a pixel.

Parameters:

• px (Point2d) – 2d point on the image plane.

• head (float) – Magnitude of head movement towards point, as compared to eye movement, where 0 is no head movement and 1 is maximum head movement.

Raises:

SocketError – In cases where message cannot be sent via socket.

move_and_rotate_base(distance: float, angle: float, speed: float | None = None, acceleration: float | None = None)

Sends both a move and a rotate command to robot.

Command translates the robot forward/backward by the desired distance and rotates it around Z axis by desired angle. If no speed/acceleration are defined, the maximum will be used. Rotational speed is calculated to match movement speed.

Warning: rotation amount is likely to be inaccurate, some trial and error may be necessary to define wanted movements.

Parameters:

• distance (float) – Motion magnitude and direction in meters.

• angle (float) – Rotation magnitude and direction in degrees.

• speed (float) – Desired peak movement speed (m/s).

• acceleration (float) – Desired peak acceleration (m/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

move_base(distance: float, speed: float | None = None, acceleration: float | None = None)

Sends a move command to robot.

Command translates the robot forward/backward by desired distance. If no speed/acceleration are defined, the maximum will be used.

Parameters:

• distance (float) – Motion magnitude and direction in meters.

• speed (float) – Desired peak speed (m/s).

• acceleration (float) – Desired peak acceleration (m/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

rotate_arms(left_angle: float, right_angle: float)

Sends rotate arms command to robot.

The arm motion is limited in the upper back and arms can not do a full rotation. Rotation is around robot’s -Y axis, 0 is straight down, positive is generally up and negative is generally down.

Parameters:

• angle_l (float) – Absolute rotation of left arm in degrees.

• angle_r (float) – Absolute rotation of right arm, in degrees.

Raises:

SocketError – In cases where message cannot be sent via socket.

rotate_base(angle: float, speed: float | None = None, acceleration: float | None = None)

Sends a rotate command to robot.

Command rotates the robot around Z axis by desired angle. If no speed/acceleration are defined, the maximum will be used.

Parameters:

• angle (float) – Rotation magnitude and direction in degrees.

• speed (float) – Desired peak speed (deg/s).

• acceleration (float) – Desired peak acceleration (deg/s²).

Raises:

• ValueError – When speed/acceleration are outside limits.

• SocketError – When message cannot be sent via socket.

tilt_base(x_percent: float, y_percent: float)

Sends tilt body command to robot.

Parameters:

• x (float) – Tilt around X axis as a fraction of maximum. -1 (left) to 1 (right).

• y (float) – Tilt around Y axis as a fraction of maximum. -1 (backwards) to 1 (forwards).

Raises:

SocketError – In cases where message cannot be sent via socket.

class navel.Perception(socket_name='/run/bodyd/vision.sock')

Bases: PerceptionMessenger

Send and receive messages from perception socket

This class is able to transceive protobuf messages via a unix domain socket (UDS). As soon as the object is created it will attempt to connect to the socket. If socket connection is successful, methods can be used to send and receive messages. Each message is converted from a protobuf format and into a navel data struct.

Parameters:

socket_name (str, optional) – Name of the socket to connect to. Defaults to NAVEL_PERCEPTION_SOCKET

clear_persist(uid: int)

Sends a message to robot to remove person from persistent storage.

Parameters:

uid (int) – Unique identifier of person.

Raises:

• ValueError – When uid is outside limits.

• SocketError – In cases where message cannot be sent via socket.

next_frame(timeout: float = 1) → Awaitable[PerceptionData]

Receives next frame of perception data from the robot.

Will always return the newest available frame, which may be from slightly before the function was called, but never a duplicate. In general, frames should arrive roughly every 0.1s.

Parameters:

timeout (float, optional) – Maximum time to wait for a frame in seconds. Defaults to 1.

Raises:

• ConnectionAbortedError – If socket connection is lost

• TimeoutError – If timeout is triggered.

Returns:

The received perception data.

Return type:

Awaitable[PerceptionData]

set_persist(uid: int)

Sends a message to robot to add person to persistent storage.

Parameters:

uid (int) – Unique identifier of person.

Raises:

• ValueError – When uid is outside limits.

• SocketError – In cases where message cannot be sent via socket.

class navel.Speech(socket_name='/run/bodyd/speech.sock')

Bases: SpeechMessenger

Send and receive messages via speech socket

This class is able to transceive protobuf messages via a unix domain socket (UDS). As soon as the object is created it will attempt to connect to the socket. If socket connection is successful, methods can be used to send messages. Each message is converted into a protobuf format before being sent to the speech socket.

It also provides a mechanism for registerig bookmarks in the text. This is run asynchronously as messages could arrive at any point in time. Read messages are accessed using callback functions. If there are no relevent callback functions then messages will be thrown away to keep buffer clear. See valid keys to see what callbacks are supported.

If the object where data is stored by callback functions is to be accessed by any other threads, steps must be taken to make it threadsafe.

Parameters:

socket_name (str, optional) – Name of the socket to connect to. Defaults to NAVEL_SPEECH_SOCKET

say(text: str)

Sends a speech text message to speech socket. If the message is too long, it may be split up and sent as parts.

Parameters:

text (str) – contents of message to be sent to speech socket.

Raises:

• TypeError – If text is not string

• SocketError – If errors connecting to socket or sending message

set_bookmark_callback(bookmark: int, action: Callable[[SpeechMessenger], Awaitable]) → None

Sets a callback for the given bookmark number.

Parameters:

• bookmark (int) – Bookmark number to bind this action to.

• action (callable) – Function that should be called. Must be async and take a reference to this object as its only parameter