Clone wiki

subt / tutorials / AddLights

Back to Tutorials

Add lights to your robots

This tutorial will show you how to equip lights on your robots.

To implement a light to your robot, you need to have a model which has <light>, <visual>, and RosFlashLightPlugin to control them. The plugin RosFlashLightPlugin is provided in the package subt_gazebo.

The model is formatted in SDF as shown in the following example. In order to include it into the URDF file of your robot, you need to define the model under <gazebo>. The second <gazebo> element in the example defines the joint of the light and your robot's body. The position of the light with respect to the parent link can be changed by the <pose> of the <model> (see line 3 in the example). In this case, the light will look like a ball and be placed 0.5 meters above the link base_link of the robot.

The parameters taken into the plugin RosFlashLightPlugin are almost the same as LedPlugin. The only difference is <service_name> representing the name of ROS service to turn on/off the light. In the example, the plugin will advertise /<robot's name>/light_model/enable.

<gazebo>
  <model name='light_model'>
    <pose>0 0 0.5 0 0 0</pose>
    <link name='light_link'>
      <visual name='light_source'>
        <pose>0 0 0 0 0 0</pose>
        <geometry>
          <sphere>
            <radius>0.025</radius>
          </sphere>
        </geometry>
        <material>
          <ambient>1 1 1 1</ambient>
          <diffuse>1 1 1 1</diffuse>
          <specular>1 1 1 1</specular>
          <emissive>0 0 0 1</emissive>
        </material>
      </visual>
      <light name='light_source' type='point'>
        <pose>0 0 0 0 0 0</pose>
        <attenuation>
          <range>0.20</range>
          <linear>0.10</linear>
        </attenuation>
        <diffuse>0 0 0 1</diffuse>
        <specular>0 0 0 1</specular>
      </light>
    </link>
    <plugin name='light_control' filename='libRosFlashLightPlugin.so'>
      <service_name>enable</service_name>
      <light>
        <id>light_link/light_source</id>
        <enable>false</enable>
        <duration>1</duration>
        <interval>0</interval>
        <color>1 1 1</color>
      </light>
    </plugin>
  </model>
</gazebo>

<gazebo>
  <joint name='light_joint' type='fixed'>
    <parent>base_link</parent>
    <child>light_model::light_link</child>
  </joint>
</gazebo>

Once you insert those lines above into the URDF of the robot, it will look like this.

light_off.jpg

Let's say this robot is named jackal. The plugin will advertise its ROS service named /jackal/light_model/enable. When you call the ROS service with true, it will turn on the light.

rosservice call /jackal/light_model/enable "data: true" 

light_on.jpg

Pre-defined lights

The package subt_gazebo has two pre-designed light models flashlight and led.

Flashlights

urdf/flashlight.urdf.xacro provides a macro named flashlight to generate a flashlight. This equipment casts directional light like a spot light and lights up objects in the dark environment. You can equip it to your own robot by inserting the macro.

It takes the following parameters:

  • flashlight_prefix (attribute, required):

    Prefix of the name of the flashlight. The name attached with the prefix will be used for ROS service name. If you are using more than one flashlight, you must choose a distinct prefix.

  • parent_link (attribute, required):

    The name of the parent link whose reference frame you use to equip the flashlight.

  • pose (element, required):

    The position of the flashlight with respect to the parent link's reference frame. At the initial pose 0 0 0 0 0 0, the flashlight faces upward.

  • plugin_params (element, required):

    The parameters taken into the RosFlashLightPlugin to setup flashing patterns of the light. If it is empty, i.e., <plugin_params></plugin_params>, it casts constant white light. Instead, you can also insert <block> to provide specific flashing patterns. The following example will flash red light for 0.5 seconds and dim it for 0.5 seconds.

    <plugin_params>
      <block>
        <duration>0.5</duration>
        <interval>0.5</interval>
        <color>1 0 0</color>
      </block>
    </plugin_params>
    

    For more details about the parameters, see the <block> parameter in http://gazebosim.org/tutorials?branch=flashlight_plugin&tut=flashlight_plugin#%3Cblock%3E.

For general specifications of macro parameters, see http://wiki.ros.org/xacro#Macros.

Let's say your robot is named your_robot and it has a link named base_link, on which a flashlight is going to be attached. You can insert the macro into the urdf file of the robot description. The following example inserts the macro at the end of the description. By the given parameters, the flashlight is named main_flashlight and will be attached on the front side of the robot. Because plugin_params is empty, the default settings are applied, i.e., constant white light.

<?xml version="1.0"?>
<robot name="your_robot" xmlns:xacro="http://www.ros.org/wiki/xacro">

  ...

  <xacro:include filename="$(find subt_gazebo)/urdf/flashlight.urdf.xacro" />

  <xacro:flashlight flashlight_prefix="main" parent_link="base_link">
    <pose>0.3 0 0.1 0 ${3.14159/2} 0</pose>
    <plugin_params></plugin_params>
  </xacro:flashlight>
</robot>

off.jpg

NOTE: the flashlight model may look different due to future updates.

Once the robot with the flashlight is spawn, you can turn it on by calling its ROS service enable under its namespace.

rosservice call /your_robot/main_flashlight/enable "data: true" 

on.jpg

You can turn it off again by giving false.

rosservice call /your_robot/main_flashlight/enable "data: false" 

LEDs

The LED model provides short-ranged but omni-directional light, which is supposed to be used to provide visual signals. The model is described in urdf/led.urdf.xacro in the package subt_gazebo. You can equip it in the same as the flashlight.

The following example gives specific parameters to the internal plugin to provide specific blinking patterns. It switches red, green, and blue colors. It flashes each color for 0.3 seconds and dims it for 0.3.

<?xml version="1.0"?>
<robot name="your_robot" xmlns:xacro="http://www.ros.org/wiki/xacro">

  ...

  <xacro:include filename="$(find subt_gazebo)/urdf/led.urdf.xacro" />

  <xacro:led led_prefix="main" parent_link="base_link">
    <pose>0 0 0.3 0 0 0</pose>
    <params>
      <block>
        <duration>0.3</duration>
        <interval>0.3</interval>
        <color>1 0 0</color>
      </block>
      <block>
        <duration>0.3</duration>
        <interval>0.3</interval>
        <color>0 1 0</color>
      </block>
      <block>
        <duration>0.3</duration>
        <interval>0.3</interval>
        <color>0 0 1</color>
      </block>
    </params>
  </xacro:led>
</robot>

Here is the results. Don't forget to call the ROS service enable to turn the LED on!

Peek 2018-08-21 10-23.gif

More lights!

You can also write your own urdf file to load multiple flashlights and LEDs as a template layout and equip them to your robot.

The following example equips three flashlights on the front side and three LEDs on the back. It first loads the two urdf files of flashlight and LED, and then uses the macro for each light.

<?xml version="1.0"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="lights">
  <xacro:property name="M_PI" value="3.14159"/>
  <xacro:include filename="$(find subt_gazebo)/urdf/flashlight.urdf.xacro" />
  <xacro:include filename="$(find subt_gazebo)/urdf/led.urdf.xacro" />

  <xacro:flashlight flashlight_prefix="right" parent_link="base_link">
    <pose>0.3 -0.3 0.3 0 ${M_PI*0.5} ${-M_PI*0.1}</pose>
    <params></params>
  </xacro:flashlight>
  <xacro:flashlight flashlight_prefix="downward" parent_link="base_link">
    <pose>0.4 0 0.4 0 ${M_PI*0.6} 0</pose>
    <params></params>
  </xacro:flashlight>
  <xacro:flashlight flashlight_prefix="left" parent_link="base_link">
    <pose>0.3 0.3 0.3 0 ${M_PI*0.5} ${M_PI*0.1}</pose>
    <params></params>
  </xacro:flashlight>

  <xacro:led led_prefix="right" parent_link="base_link">
    <pose>-0.3 -0.3 0.3 0 0 0</pose>
    <params>
      <duration>0.3</duration>
      <interval>0.3</interval>
      <color>1 0.8 0</color>
    </params>
  </xacro:led>
  <xacro:led led_prefix="center" parent_link="base_link">
    <pose>-0.3 0 0.3 0 0 0</pose>
    <params>
      <block>
        <duration>0.1</duration>
        <interval>0</interval>
        <color>1 0 0</color>
      </block>
      <block>
        <duration>0.1</duration>
        <interval>0</interval>
        <color>0 1 0</color>
      </block>
      <block>
        <duration>0.1</duration>
        <interval>0</interval>
        <color>0 0 1</color>
      </block>
    </params>
  </xacro:led>
  <xacro:led led_prefix="left" parent_link="base_link">
    <pose>-0.3 0.3 0.3 0 0 0</pose>
    <params>
      <duration>0.3</duration>
      <interval>0.3</interval>
      <color>1 0.8 0</color>
    </params>
  </xacro:led>
</robot>

When you include the template in your robot's urdf file, it should look like this.

temp.jpg

Back to Tutorials

Updated