Niryo_robot_led_ring

This package is the one managing the LED Ring of Ned2.

It is composed of one node, receiving commands and the current robot status, and publishing LED Ring states.

The LED Ring is composed of 30 WS2811 RGB LEDs, controlled by the package with the rpi_ws281x library.

LED Ring node

The ROS Node is made to manage the LED Ring state, and to publish its currents status and state on ROS topics. It uses a class implementing several animation (11 for now), allowing to control the LED Ring or to display the current robot status. The LED Ring is also implemented in Rviz.

The LED Ring can either be:

• in ROBOT STATUS mode: the LED is displaying the status of the robot.

• in USER mode: the user can control the LED Ring with the several methods implemented, through

  Blockly , Pyniryo or Python ROS Wrapper .

Robot status mode

When displaying the robot status, the LED Ring has several states which represent different modes and error status. Refer to the following table. The node subscribes to the ROS topic /niryo_robot_status/robot_status, published by the package RobotStatus.

Animation and color	Description	Troubleshooting
White Breath	Robot is booting	N/A
Blue Chase	Calibration is needed	Press the Custom button, or launch a calibration
Blue Snake	Calibration in progress	N/A
Blue Breath	Free Motion enabled	N/A
3 Yellow Flashing	Calibration start	N/A
Green Breath	Free Motion disabled, torque enabled	N/A
Solid Green	Program in progress	N/A
Green Chase	Program paused	Long press on the TOP button to cancel the program, short press to resume
Orange Breath	Program execution error	Launch a new action to clear this state
Flashing Orange	Collision	Launch a new action to clear this state
Solid Orange	Joint out of bounds	Switch to Free Motion mode to bring the joints within limits.
1 Purple Flashing	New connection form Niryo Studio	N/A
2 Purple Flashing	Save a robot positions from the ‘Save’ button	N/A
Flashing Red	Motor error / Raspberry overheating	Please check the error on Niryo Studio.
Solid Red	ROS Crash	Please restart the robot.

User mode

Several animations are implemented to allow the user different ways to control the LED Ring. Refer to the following table. The node receives commands through the service /niryo_robot_led_ring/set_user_animation (see the service section)

Important

Ned must be in autonomous mode in order to allow the user to control the LED Ring.

Animation	Appearance	Gif
None	LEDs are turned off
Solid	Set the whole LED Ring to the same color at once
Flashing	Flashes a color according to a frequency
Alternate	The different colors are alternated one after the other.
Chase	Movie theater light style chase animation.
Color Wipe	Wipe a color across the LED Ring. Similar to go_up, but LEDs are not turned off at the end.
Rainbow	Draws rainbow that fades across all LEDs at once.
Rainbow cycle	Draw rainbow that uniformly distributes itself across all LEDs.
Rainbow chase	Rainbow chase animation.
Go up	LEDs turn on like a loading circle until lighting up the whole LED Ring. and are then all turned off at the same time.
Go up and down	Like go_up, but LEDs are turned off the same way they are turned on.
Breath	Variation of light intensity to imitate breathing.
Snake	Luminous snake that turns around the LED Ring.

Note

When displaying the robot status, the LED Ring commander uses those methods, with the default parameters defined below.

It belongs to the ROS namespace: /niryo_robot_led_ring/.

Parameters - LED Ring

Firstly, the LED Ring component, controlled with the rpi_ws281x library, through the Python class PixelStrip, is parameterizable. Default parameters are set in the led_strim_params.yaml file of the /config folder of the package

Parameters of the Led Ring component

Name	Description	Default value
led_count	Number of LED pixels in the LED Ring	30
led_pin	Raspberry Pi GPIO pin connected to the pixels It must support PWM.	13
led_freq_hs	LED signal frequency in Hertz	800khz
led_dma	DMA channel to use for generating signal	10
led_brightness	LEDs brightness. Set to 0 for darkest and 255 for brightest	255
led_invert	True to invert the signal (when using NPN transistor level shift)	True
led_channel	the PWM channel to use	0

Another configuration file, the led_ring_params.yaml, sets the default parameters of LED Ring animations.

Parameters of the LED Ring animations

Name	Description	Default value
default_flashing_period	Default Flashing animation period in seconds	0.25
default_alternate_period	Default Alternate animation period in seconds	1
default_chase_period	Default Chase animation period in seconds	4
default_colorwipe_period	Default Wipe animation period in seconds	5
default_rainbow_period	Default Rainbow animation period in seconds	5
default_rainbowcycle_period	Default Rainbow cycle animation period in seconds	5
default_rainbowchase_period	Default Rainbow chase animation period in seconds	5
default_goup_period	Default Go up animation period in seconds	5
default_goupanddown_period	Default Go up and down animation period in seconds	5
default_breath_period	Default Breath animation period in seconds	4
default_snake_period	Default Snake animation period in seconds	1.5
led_offset	Offset ID between the LED with the ID 0 and the ID of the LED at the back of the robot.	8
simulation_led_ring_markers_publish_rate	Rviz LED ring markers publishinf rate in simulation mode	20
led_ring_markers_publish_rate	Rviz LED ring markers publishing rate on a real robot	5

Services - LED Ring

The ROS node implements one service, designed for the user to control the LED Ring.

LED Ring Package services

Name	Message type	Description
set_user_animation	LedUser	Allows user to control the LED Ring, with implemented animations. A new request will interrupt the previous one, if still playing. Depending on the wait boolean field and the iterations field of the request, the service will either answer immediately after launching the animation, or wait for the animation to finish to answer.
set_led_color	SetLedColor	Lights up a LED identified by an ID

Publishers - LED Ring

LED Ring Package publishers

Name	Message type	Description
led_ring_status	LedRingStatus	Publishes the status of the LED Ring, providing information on the current mode (displaying robot status or controlled by user if the robot works in AUTONOMOUS mode), the current animation played and the animation color (except for rainbow methods, where the animation color is not defined). Publishes every time at least one field changed.
visualization_marker_array	visualization_msgs/MarkerArray	Publishes shapes representing LEDs when Ned is used in simulation with Rviz, as a list of 30 visualization_msgs/Marker of size 30.

Subscribers - LED Ring

LED Ring Package subscribers

Topic name	Message type	Description
/niryo_robot_status/robot_status	RobotStatus	Retrieves the current robot status, and control LED accordingly (see Niryo_robot_status section)
/niryo_robot/blockly/save_current_point	std_msgs/Int32	Catches the ‘Save Point’ action to make the LED ring blink.
/niryo_studio_connection	std_msgs/Empty	Catches the Niryo Studio connection to make the LED ring blink.

Dependencies - LED Ring

• niryo_robot_msgs
• std_msgs
• visualization_msgs
• rpi_ws281x==4.3.0

Services files - LED Ring

LedUser (Service)

niryo_robot_led_ring/LedRingAnimation animation_mode

std_msgs/ColorRGBA[] colors
float64 period         # Time of 1 iteration in seconds
int16 iterations

# The service either wait for the iterations to finish to answer, 
# or answer immediatly a Success after launching the function of Led Ring control. 
# if iterations is 0, answer immediatly in any case, because the function never
# stops.
bool wait_end

---
int32 status
string message

SetLedColor (Service)

int8 led_id
std_msgs/ColorRGBA color

---
int32 status
string message

Messages files - LED Ring

LedRingAnimation (Message)

int32 NONE = -1
int32 SOLID = 1
int32 FLASHING = 2   
int32 ALTERNATE = 3  
int32 CHASE = 4       
int32 COLOR_WIPE = 5   
int32 RAINBOW = 6
int32 RAINBOW_CYLE = 7
int32 RAINBOW_CHASE = 8
int32 GO_UP = 9
int32 GO_UP_AND_DOWN = 10
int32 BREATH = 11
int32 SNAKE = 12
int32 CUSTOM = 13

int32 animation

LedRingCurrentState (Message)

Header header
std_msgs/ColorRGBA[] led_ring_colors

LedRingStatus (Message)

int32 ROBOT_STATUS = 1
int32 USER = 2

int32 led_mode

niryo_robot_led_ring/LedRingAnimation animation_mode

std_msgs/ColorRGBA animation_color # except for rainbow related animation

LED Ring API functions

In order to control the robot more easily than calling each topics & services one by one, a Python ROS Wrapper has been built on top of ROS.

For instance, a script turning on the LED Ring via Python ROS Wrapper will look like:

from niryo_robot_led_ring.api import LedRingRosWrapper

led_ring = LedRingRosWrapper()
led_ring.solid(color=[255, 255, 255])

This class allows you to control the robot via internal API. By controlling, we mean using the LED ring

List of functions subsections:

Custom animations functions

class LedRingRosWrapper(hardware_version='ned2', service_timeout=1)

set_led_color(led_id, color)

Lights up an LED in one colour. RGB colour between 0 and 255.

Example:

from std_msgs.msg import ColorRGBA

led_ring.set_led_color(5, [15, 50, 255])
led_ring.set_led_color(5, ColorRGBA(r=15, g=50, b=255))

Parameters:

• led_id (int) – Id of the led: between 0 and 29
• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.

Returns:

status, message

Return type:

(int, str)

custom(led_colors)

Sends a colour command to all LEDs of the LED ring. The function expects a list of colours for the 30 LEDs of the robot.

Example:

led_list = [[i / 30. * 255 , 0, 255 - i / 30.] for i in range(30)]
led_ring.custom(led_list)

Parameters:led_colors (list[list[float] or ColorRGBA]) – List of size 30 of led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255. Returns:status, message Return type:(int, str)

Pre-made animations functions

class LedRingRosWrapper(hardware_version='ned2', service_timeout=1)

solid(color, wait=False)

Sets the whole Led Ring to a fixed color.

Example:

from std_msgs.msg import ColorRGBA

led_ring.solid([15, 50, 255])
led_ring.solid(ColorRGBA(r=15, g=50, b=255), True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• wait (bool) – The service wait for the animation to finish or not to answer. For this method, the action is quickly done, so waiting doesn’t take a lot of time.

Returns:

status, message

Return type:

(int, str)

turn_off(wait=False)

Turns off all Leds

Example:

led_ring.turn_off()

Parameters:wait (bool) – The service wait for the animation to finish or not to answer. For this method, the action is quickly done, so waiting doesn’t take a lot of time. Returns:status, message Return type:(int, str)

flashing(color, period=0, iterations=0, wait=False)

Flashes a color according to a frequency. The frequency is equal to 1 / period.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.flashing([15, 50, 255])
led_ring.flashing([15, 50, 255], 1, 100, True)
led_ring.flashing([15, 50, 255], iterations=20, wait=True)

frequency = 20  # Hz
total_duration = 10 # seconds
led_ring.flashing(ColorRGBA(r=15, g=50, b=255), 1./frequency, total_duration * frequency , True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive flashes. If 0, the Led Ring flashes endlessly.
• wait (bool) – The service wait for the animation to finish all iterations or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

alternate(color_list, period=0, iterations=0, wait=False)

Several colors are alternated one after the other.

Examples:

from std_msgs.msg import ColorRGBA

color_list = [
    ColorRGBA(r=15, g=50, b=255),
    [255, 0, 0],
    [0, 255, 0],
]

led_ring.alternate(color_list)
led_ring.alternate(color_list, 1, 100, True)
led_ring.alternate(color_list, iterations=20, wait=True)

Parameters:

• color_list (list[list[float] or ColorRGBA]) – Led color list of lists of size 3[R, G, B] or ColorRGBA objects. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive alternations. If 0, the Led Ring alternates endlessly.
• wait (bool) – The service wait for the animation to finish all iterations or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

chase(color, period=0, iterations=0, wait=False)

Movie theater light style chaser animation.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.chase(ColorRGBA(r=15, g=50, b=255))
led_ring.chase([15, 50, 255], 1, 100, True)
led_ring.chase(ColorRGBA(r=15, g=50, b=255), iterations=20, wait=True)

Parameters:

• color (list or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive chase. If 0, the animation continues endlessly. One chase just lights one Led every 3 Leds.
• wait (bool) – The service wait for the animation to finish all iterations or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

wipe(color, period=0, wait=False)

Wipes a color across the LED Ring, light a LED at a time.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.wipe(ColorRGBA(r=15, g=50, b=255))
led_ring.wipe([15, 50, 255], 1, True)
led_ring.wipe(ColorRGBA(r=15, g=50, b=255), wait=True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• wait (bool) – The service wait for the animation to finish or not to answer.

Returns:

status, message

Return type:

(int, str)

rainbow(period=0, iterations=0, wait=False)

Draws rainbow that fades across all LEDs at once.

Examples:

led_ring.rainbow()
led_ring.rainbow(5, 2, True)
led_ring.rainbow(wait=True)

Parameters:

• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive rainbows. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

rainbow_cycle(period=0, iterations=0, wait=False)

Draws rainbow that uniformly distributes itself across all LEDs.

Examples:

led_ring.rainbow_cycle()
led_ring.rainbow_cycle(5, 2, True)
led_ring.rainbow_cycle(wait=True)

Parameters:

• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive rainbow cycles. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

rainbow_chase(period=0, iterations=0, wait=False)

Rainbow chase animation, like the led_ring_chase method.

Examples:

led_ring.rainbow_chase()
led_ring.rainbow_chase(5, 2, True)
led_ring.rainbow_chase(wait=True)

Parameters:

• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive rainbow cycles. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

go_up(color, period=0, iterations=0, wait=False)

LEDs turn on like a loading circle, and are then all turned off at once.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.go_up(ColorRGBA(r=15, g=50, b=255))
led_ring.go_up([15, 50, 255], 1, 100, True)
led_ring.go_up(ColorRGBA(r=15, g=50, b=255), iterations=20, wait=True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive turns around the Led Ring. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

go_up_down(color, period=0, iterations=0, wait=False)

LEDs turn on like a loading circle, and are turned off the same way.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.go_up_down(ColorRGBA(r=15, g=50, b=255))
led_ring.go_up_down([15, 50, 255], 1, 100, True)
led_ring.go_up_down(ColorRGBA(r=15, g=50, b=255), iterations=20, wait=True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive turns around the Led Ring. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

breath(color, period=0, iterations=0, wait=False)

Variation of the light intensity of the LED ring, similar to human breathing.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.breath(ColorRGBA(r=15, g=50, b=255))
led_ring.breath([15, 50, 255], 1, 100, True)
led_ring.breath(ColorRGBA(r=15, g=50, b=255), iterations=20, wait=True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default time will be used.
• iterations (int) – Number of consecutive turns around the Led Ring. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)

snake(color, period=0, iterations=0, wait=False)

A small coloured snake (certainly a python :D ) runs around the LED ring.

Examples:

from std_msgs.msg import ColorRGBA

led_ring.snake(ColorRGBA(r=15, g=50, b=255))
led_ring.snake([15, 50, 255], 1, 100, True)
led_ring.snake(ColorRGBA(r=15, g=50, b=255), iterations=20, wait=True)

Parameters:

• color (list[float] or ColorRGBA) – Led color in a list of size 3[R, G, B] or in an ColorRGBA object. RGB channels from 0 to 255.
• period (float) – Execution time for a pattern in seconds. If 0, the default duration will be used.
• iterations (int) – Number of consecutive turns around the Led Ring. If 0, the animation continues endlessly.
• wait (bool) – The service wait for the animation to finish or not to answer. If iterations is 0, the service answers immediately.

Returns:

status, message

Return type:

(int, str)