Using Lightning

Starting Lightning

An environment server must already be started for Lightning to work.

Also, make sure that the ROBOT environment variable and robot_description parameter are set for the machine that Lightning is running for.

To start lightning with the default parameters, run the following command:
roslaunch lightning lightning.launch

To start lightning with custom parameters, create a launch file and place the following line in it:
<include file="$(find lightning)/launch/lightning.launch">
Set the desired parameters after the above line:
<param name="<parameter_name>" value="<parameter_value>" />

Lightning Parameters

All of the Lightning parameters are within the /lightning namespace (e.g. /lightning/robot_name).

robot_name (default=pr2)

Name of your robot. This determines which path librar(ies) to use.

step_size (default=0.02)

Step size to use between path points.

draw_points (default=false)

Set to true if rviz and the point_drawer node are being started and you want to view planning data in rviz. Otherwise, set it to false.

allowed_planning_time (default=20.0)

Timeout for planning.

collision_check_service/num_threads (default=4)

Number of threads to use for collision checking.

path_shortcutter_service/num_iterations (default=200)

Number of attempts to shortcut the path.

path_shortcutter_service/ignore_fraction (default=0.1)

The path shortcutter does not attempt to shortcut between two points if the current path between them is already almost a line. This parameter controls what the shortcutter thinks is "almost a line". The higher the value, the more path sections the shortcutter will not try to shortcut. This value must be in the interval (0, 1).

rr_node/num_rr_planners (default=2)

Number of planners used for retrieve-repair. If a retrieved path has multiple invalid sections, then those sections are replanned in parallel. This parameter specifies how many invalid sections are replanned in at one time. If there are more invalid sections than RR planners, then some go into a queue and are repaired when a planner finishes and becomes available. The planners must be started separately. If this value is changed, then ompl_planning.launch must also be changed. To start another planner, see the ompl_planning.launch file for an example.

rr_node/path_library_path_node_size (default=8)

Number of paths that can be stored in a single file for new libraries.

rr_node/path_library_sg_node_size (default=50)

Number of start-goal pairs that can be stored in a single file for new libraries. This must be higher than path_library_path_node_size.

rr_node/num_paths_to_collision_check (default=4)

Number of paths to that the library needs to collision check. The higher this value is, the more likely a better path will be retrieved for repair. However, the higher this value is, the more time will be needed to check collisions before a path can be repaired. It is recommended that this value is a multiple of collision_check_service/num_threads.

rr_node/dtw_distance (default=5.0)

This value determines how "different" repaired paths need to be so they are stored in the library. In general, more repaired paths will be stored if this value is lower.

rr_node/path_library_dir (default=$(find lightning)/src/pathlib/paths)

The library directory to use.

lightning/store_paths (default=true)

Set to false if you do not want to store paths in the library when planning.

lightning/use_RR (default=true)

Set to false if you do not want to use retrieve-repair.

lightning/use_PFS (default=true)

Set to false if you do not want to use planning-from-scratch.

Using Lightning

Lightning uses the arm_navigation_msgs/GetMotionPlan service.

Lightning is a Service listening for requests on "lightning/lightning_get_path". In the request that is sent, only set the following fields:

1. motion_plan_request.group_name
2. motion_plan_request.start_state.joint_state.name
3. motion_plan_request.start_state.joint_state.position
4. motion_plan_request.goal_constraints.joint_constraints[i].joint_name
5. motion_plan_request.goal_constraints.joint_constraints[i].position
6. motion_plan_request.allowed_planning_time

The robot_name parameter and the joint_names provided in the GetMotionPlan request determine the path library that is used for retrieving paths and storing them. Different libraries are created and used for different combinations of robot_name and joint_names. Libraries are saved even after Lightning is shut down.

If you are using the same robot (and same joints) in different environments, make sure that the robot name parameter is unique for each different environment. Otherwise, path libraries for different environments will be mixed.

The Lightning planner does not currently handle position constraints or tolerances.

Lightning will return the planned path in trajectory.joint_trajectory.points.

Library Management

Library Management through Lightning

In addition to having Lightning interface with the path librar(ies), you can as well.

There are three management actions for the librar(ies): storing a path, deleting a path, and deleting a library. When Lightning is running, send ManagePathLibrary service requests to "manage_path_library" to perform these actions.

1. Storing a path:

   • Set the action to ACTION_STORE.
   • Put the path to store in path_to_store, an array of JointTrajectoryPoints.
   • Specify the robot_name and the joint_names, as those define which library to use. If the library for the given robot name and joint names does not exist, a new one will be created.
   • The retrieved_path field should be left as an empty array.

2. Deleting a path:

   • Set the action to DELETE_PATH.
   • Set the path_id field to be the id of the path you want to delete.
   • Again, specify the robot name and the joint names corresponding to the
     library that is to be changed.

3. Deleting a library:

   • Set the action to DELETE_LIBRARY.
   • Send the robot name and joint names corresponding to the library that is to be deleted.

Manual Library Management

You can also delete a library from the command line when Lightning is not running.

1. Go into the lightning package: roscd lightning
2. Go into the paths directory: cd src/pathlib/paths
3. Remove the directory that corresponds to the library that you want to delete with the rm -r command.
   • The library directories are named with the following structure: paths_\<unique_id>_\<robot_name>. To make sure you are deleting the correct library, check that the robot name and joint names in the _lib_info file in the library directory to be deleted are the right ones.