Developer's Guide

# Welcome to the Wiki! A more detailed explanation of how things work under the hood will be explained here, for future developers to have an easier transition. Scroll to the bottom for a list of potential to-do items and suggestions.

Updated: 14/7/2020

Program breakdown

There are 5 scripts that control the bulk of the experiment logic/flow, namely:

1. postercombiner.py
2. gui.py
3. Experiment.py
4. controller_joystick.py
5. map.py

• postercombiner.py

Node:

1. curr_posters

Subscribing to:

1. poster - PoseStamped
2. trigger_msgs - Int16
3. file_name - String

Publishing to:

1. poster_comb - PoseArray
2. poster_comb_text - MarkerArray

Description:

This script mainly interfaces with Rviz to enable poster (reward zone) modification and visualization. It receives the file_name which is a csv file specified by the user in a drop down menu. The right csv file is then parsed and visualization info sent to Rviz with poster_comb and poster_comb_text.

It also receives new poster locations specified by the user in Rviz through the poster topic. Modifications will be made to the actual csv file specified by file_name, and updated visualization information sent through poster_comb and poster_comb_text.

The above behavior will continue until a locking mechanism get's toggled (so that users will not accidentally modify rewards during the actual experiment. The locking mechanism interfaces with the Experiment.py script, which publishes trigger_msgs. It stops updating when it receives any new messages from the topic, unless the message is 55, which indicates that the experiment has ended and reward modifications can resume.

• gui.py

Node:

1. gui_selection

Publishing to:

1. file_name - String
2. gui_settings - String (JSON form)

Description:

This script uses QT framework to create a graphical interface, allowing users to set experiment parameters. Sends postercombiner.py the current csv file to edit through file_name topic. On clicking the start button, parameters are saved to a eparams.pkl file, and the Experiment.py script gets called.

gui_settings topic is used as a fix to correctly load the gui settings for controller joystick. This topic can be used further for parameter settings instead of loading from pkl file.

• Experiment.py

Node:

1. triggers

Subscribing to:

1. amcl_pose - PoseWithCovarianceStamped

Publishing to:

1. current_poster - PoseStamped
2. trigger_msgs - Int16

Description:

This script mainly controls the actual experiment and trials. Experiment parameters are read in from eparams.pkl. Recording of data is also controlled here - rosbag with ros timing, csv with psychopy timing. It publishes a number to trigger_msgs to denote different stages of the experiment. The tens digit signify trial stage (cue onset, cue offset, end of trial, end of experiment), and the ones digit codes for reward ID.

On each new trial, the new selected poster location is sent to Rviz through current_poster for displaying purposes. A message is also sent through ./tcp-server to the iPad/iPhone to display the target poster. Trial timings are tracked using psychopy timers. The script listens to key-presses (p, r, t, y, n) for user interaction.

• controller_joystick.py

Node:

1. base_scan

Subscribing to:

1. base_scan - LaserScan
2. joy - Joy
3. trigger_msgs - Int16

Publishing to:

1. RosAria/cmd_vel - Twist

Description:

Maps secondary joystick input (joy) and controls whether it is allowed to actually move the platform. Speed is (see to-do) throttled based on distance to wall, determined by LIDAR base_scan. It also listens to trigger_msgs to lock the secondary joystick during the cue-onset period.

• map.py

Node:

1. Post_Process

Subscribing to:

1. map - OccupancyGrid
2. base_scan - LaserScan
3. particlecloud - PoseArray
4. amcl_pose - PoseWithCovarianceStamped

Publishing to:

1. initialpose - PoseWithCovarianceStamped

Description:

This script performs post-process amcl with scan-matching proposed in this paper. The scan matching program has three class: OccupancyMap to handle the environment mapping and occupancy matrix matching with point coordinates; LaserSubs to convert laser scan data to 2d coordinate; PoseArray to check for particlecloud update and cloud convergence criteria; and PostProcessPose to handle the algorithmic matching, publish result to initial poses.

Eyelink branch

1. Eyelink Calibration is done via this
2. Eyelink.py is the class file for eyelink to start, end and save recording of the eyelink file
3. calibrate_video.py is the file to perform set1 experiment

To-do

1. Some measurement for controller joystick for obstacle avoidance is a bit off, unclear of how the conversion to meter is done in gui page
2. Improve AMCL localization (fixed with map.py, tested for elevator L area in maptest1.pgm, tests for the maze may be needed)
3. Check that the parameters, loading and saving in gui.py are all working fine (as of last update, only the maze, platform page has been rigorously tested, some pages are outdated/ unused)
4. Set up hardware connection for Ripple (LPT). Hardware for Eyelink is completed
5. Tests for Eyelink during navigation is required
6. Insert script into existing code for Ripple (trigger recording and saving around Experiment.py)
7. Experiment script now accounts for poster direction and platform direction (Rigorous testing still needed, angle tolerance should be smaller than 90).
8. Reward definition stage hard-codes number of rewards to 6, in postercombiner.py, to_store variable [QOL improvement]
9. Now unable to create new csv files from gui.py [QOL improvement]
10. Some paths still need to be fixed to be relative [QOL improvement]
11. Catch improper experiment termination, killing rosbags etc properly [QOL improvement]