This repository contains the documentation and code for the Loki robot.

Loki is a small robot that is intended to be a used to learn how to use ROS (Robot Operating System.) ROS runs on a Raspberry Pi 3 computer board and it plugs into the Loki printed circuit board to access 2 motors with drive electronics and wheel encoders, 16 sonars, a 8 mega pixel camera, a 4 degree of freedom Arm, and a 6000mAH battery. Using a USB Wireless dongle, software is developed on a laptop/desktop system and downloaded into the Raspberry Pi 3 processor board.

• Runs ROS (Robot Operating System) on a Raspberry Pi 3 computer.

• Dimensions: 250mm (L) x 110mm (W) x ~200mm (H)

• Battery: 6000mAH Lithium-Ion Battery Pack

• Sonars: 16 HC-SR04 sonars

• Motors: 2 Micro Metal Gearmotors 298:1 Gear Redution

• Wheels: 70mm (D) x 8mm (W)

• Encoders: 16.26 ticks/mm

• Speed: 1 M/Sec

• Embedded Processor: 20MHz @ 5V Atmel ATmega2560 (Arduino Mega compatible)

• Arm: 4 degree of freedom Me Arm 0.4

• LED's: 8

• Expansion: 2x5 .1in Expansion Bus Connector

• Camera: Upward pointing Raspberry Pi v2 Camera (3280 × 2464 pixels)

(These instructions are too brief!!!)

Do the following:

1. Make sure that source ./devel/setup.bash is in your ~/.bashrc file.

2. Make sure that the correct my_arduino_params.yaml file.

    cd ~/catkin_ws/src/ros_arduino_bridge/ros_arduino_python/config
    cp my_arduino_params.yaml.loki my_arduino_params.yaml
   

3. Set up the RasPi3 serial port:

    # Wayne: Do we really need to do this?
    sudo mgetty -s 115200 /dev/ttyAMA0
   

4. Make sure that the ROS_MASTER_URI environment variable is the same on both your laptop and on the RasPi3. (This is a bit involved and we may add to this section later as needed):

    env | grep ROS_MASTER_URI     # Show settings of env. var.
    export ROS_MASTER_URI=http://ubuntu.local:11311  # Set env var.
   

5. Hit the reset switch on the Loki near the green leds and then

    roslaunch ros_arduino_python arduino.launch
   

   You must not see any errors that stop the launch.

6. Get the sonar locations published. Log into the RasPi again and run the following command:

    # Launch file is located in fiducials_lib for obscure reasons:
    roslaunch fiducials_lib loki.launch
   

For the PS3 Controller:

1. Make sure your controller is charged.

2. For joystick control you need either the PS2 or XBox usb dongle pluged into the RasPi.

3. Pair your controller. (XBox: Tiny reset in back then press chrome X key, PS2: Hold select key). Run the following command on the RasPi:

    roslaunch joy_input joystick.launch
   

4. Hold the left hand button with index finger then left joystick will control Robot movements

Fiducial SLAM:

1. To run fiducial localization you need a calibrated camera 'yaml' file and the size of your fiducials needs to be setup in a fiducial launch file.

2. Run 'roslaunch fiducial_slam fiducial_raspi_3d.launch` on RasPi

This stuff may be getting old:

Do the following: (The first setup step is a turse set of reminders and not detailed)

1. Initial setup includes booting the RasPi and the source ./devel/setup.bash done. Have the my_arduino_params.yaml file copied over from my_arduino_params.yaml.loki Run 'sudo mgetty -s 115200 /dev/ttyAMA0' on the RaspPi2 to setup serial port To run fiducial localization you need a calibrated camera 'yaml' file and the size of your fiducials needs to be setup in a fiducial launch file. Properly configure ROS_MASTER_URI on the RaspPi as well as laptop to run 'rviz'. (This is a bit involved and we may add to this section later as needed)

2. Hit the reset switch on the Loki near the green leds and then Run roslaunch ros_arduino_python arduino.launch on RasPi You must not see any errors that stop the launch.

3. For joystick control you need either the PS2 or XBox usb dongle pluged into the RasPi. You will have to plug it into USB then pair as follows:

   XBox: Press tiny reset button in back if you have not paired before. If you have paired before press big chrome X button.

   PS3: Set the slide switch on the USB dongle to Xinput to emulate XBox protocol. Plug it in and on hand controller press the 'P3' button in center down till only one of the 4 leds is on then you are paired and dongle led is solid red.

   After pairing run 'roslaunch joy_input joystick.launch'

   Once joystick node is running hold down the button on front of left side of controller while then using left joystick to control velocity. You should get /cmd_vel commands to the robot but have to keep moving joystick or the bot times out in 2 sec.

4. For Fiducial maps: Run 'roslaunch fiducial_slam fiducial_raspi_3d.launch` on RasPi2

   (mjstn - Is this True????: Run roslaunch fiducial_lib loki.launch on laptop) (For details refer to: https://github.com/UbiquityRobotics/fiducials README.md)

5. Run rviz on laptop.

   • In left sidebar, under Global Option change Fixed Frame to base_link`.

   • Click on [Add] and select Range. You will need to do this 16 times, because there are 16 sonars.

   • Under Range=>Topic, select the correct topic to listen to. This will be one of /arduino/sensor/sensor_1 through /arduino/sensor/sensor_16.

   • Rinse, Lather, Repeat.

The software environment for the bus_loki is more complicated than we would like. The bus_loki deliberately uses an ATmega2560 microcontroller to be as compatible as possible with the Arduino community.

For a variety of reasons, the code is spread across multiple repositories. Furthermore, some of these other repositories have other dependencies that are annoying (e.g. the bus_raspberry_pi depends upon ATmega324P support, which is not readily available.) To be consistent across all of these repositories, requires more effort. In addition, the Arduino-IDE does not play nice with version control systems. So, we use a fairly popular alternative called Arduino-Makefile which uses fairly standard Makefiles and standalone editors (e.g. vim or emacs) to develop Arduino code that is complatible with the Arduino IDE.

To set things up:

    cd .../catkin_ws/src
    git clone https://github.com/UbiquityRobotics/Arduino-Makefile.git
    git clone https://github.com/UbiquityRobotics/bus_common.git
    git clone https://github.com/UbiquityRobotics/bus_loki.git
    git clone https://github.com/UbiquityRobotics/bus_server.git
    git clone https://github.com/UbiquityRobotics/bus_slave.git
    # The following command downloads ~2GB of git version control stuff.
    # Even with a fast link it takes a while...
    git clone https://github.com/UbiquityRobotics/Arduino.git

Next, we need to bring over all the compilers and stuff to support the AVR compilation environment:

    sudo apt-get avr-libc avrdude binutils-avr gcc-avr
    # We also need GNU make:
    sudo apt-get install build-essential

The bootloader is installed onto Loki using the Arduino IDE.

For Loki Rev. C, the 2x3 ISP header N26 does not properly connect to RESET. The work around is to use patch cables to connect the programmer header to various test points on Loki. The table below shows the six connections:

Signal	Programmer	Loki
MISO	Pin 1	TP8
VREF	Pin 2	TP31
SCK	Pin 3	TP10
MOSI	Pin 4	TP9
RESET	Pin 5	TP5
GND	Pin 6	TP32

Perform the following steps:

1. Make sure you have the Arduino IDE installed:

    sudo apt-get install arduino
   

2. Start the Arduino IDE. (You may need to run it as sudo arduino in order to give avrdude access to the USB device.)

3. Using the [Tools] pull down menu, select [Board] => [Arduino Mega 2560 or Mega ADK]

4. Using the [Programmer] pull down menu, select the appropriate programmer.

5. Connect the programmer 2x3 connector to the Loki test pins as shown in the table above for Loki Rev. C. For Rev. D and on, just connect to the 2x3 ISP connector N26.

6. Connect your programmer to your laptop/desktop.

7. Using the [Tools] pull down menu, select [Burn Bootloader].

That should do it.

When all of the dust settles, you should be able to do the following:

    cd .../catkin_ws/src/bus_loki
    make
    make upload       # Read below for more about uploading

(Random comment: Make sure that C10 is installed.)

The actual code that implements the firmware starts in bus_loki.ino. The key line is:

    #define TEST TEST_...

The values for TEST_... are found in ../bus_server/bus_server.h:

• TEST_BUS_OUTPUT outputs a stream of chacters on the serial port.
• TEST_BUS_ECHO is a strange bus debugging mode (too hard to explain.)
• TEST_BUS_COMMAND blinks an LED on the motor controller board.
• TEST_BUS_BRIDGE runs the software as a bus bridge.
• TEST_BUS_LINE runs the ROS Arduino Bridge protocol.

To compile the code, type:

    make

The make upload target expects you to have USB-serial cable plugged into your laptop/desktop. We use the DFRobot FTDI Basic Breakout board. This board has two features that we like:

• One you can select between 3.3V and 5V. We always use 3.3V. Ground is pin 1 and plugs into pin 1 of N4 on the bus_loki.

• It puts DTR on pin 6 instead of RTS. The DTR signal is what the Arduinos use for their reset signal.

The DFRobot board requires a USB-A to mini-USB-B cable. We purchased ours from Jameco (part number: 2152243.)

To upload the firmware, do the following:

1. Plug the serial download cable into your laptop/desktop.

2. Plug the serial download cable to into N4 on the bus_loki. Make sure the GND is connected to pin 1 (which is labeled on the Loki board.)

3. Type the following:

    make upload
   

That should do it.

Port	Pin	Use	Arduino
PE0	2	UART0_RXD	0
PE1	3	UART0_TXD	1
PE3	5	MOTOR2_INPUT1	5
PE4	6	MOTOR2_ENABLE	2
PE5	7	MOTOR2_INPUT2	3
PH3	15	SERVO1	6
PH4	16	SERVO2	7
PH5	17	SERVO3	8
PH6	18	SERVO4	9
PB1	20	SCK	52
PB2	21	MOSI	51
PB3	22	MISO	50
PB4	23	ENCODER_R1	10
PB5	24	ENCODER_R2	11
PB6	25	ENCODER_L1	12
PB7	26	ENCODER_L2	13
PL0	35	S_TRIG14	49
PL1	36	S_TRIG13	48
PL2	37	S_TRIG12	47
PL3	38	S_TRIG11	46
PL4	41	MOTOR1_INPUT1	43
PL5	40	MOTOR1_INPUT2	44
PL6	39	MOTOR1_ENABLE	45
PD0	43	SCL	21
PD1	44	SDA	20
PD2	45	UART1_RXD	19
PD3	46	UART1_TXD	18
PG4	29	S_TRIG15	-
PG3	28	S_TRIG16	-
PG2	70	S_TRIG1	39
PG1	52	BUS_STANDBY	40
PK0	89	S_ECHO8	A8
PK1	88	S_ECHO7	A9
PK2	87	S_ECHO6	A10
PK3	86	S_ECHO5	A11
PK4	85	S_ECHO4	A12
PK5	84	S_ECHO3	A13
PK6	83	S_ECHO2	A14
PK7	82	S_ECHO1	A15
PA0	78	S_TRIG2	22
PA1	77	S_TRIG3	23
PA2	76	S_TRIG4	24
PA3	75	S_TRIG5	25
PA4	74	S_TRIG6	26
PA5	73	S_TRIG7	27
PA6	72	S_TRIG8	28
PA7	71	S_TRIG9	29
PJ7	79	S_TRIG10	-
PJ6	69	S_ECHO9	-
PJ5	68	S_ECHO10	-
PJ4	67	S_ECHO11	-
PJ3	67	S_ECHO12	-
PJ2	65	S_ECHO13_14	-
PJ1	64	S_ECHO15_16	14
PC7	60	LED8	30
PC6	59	LED7	31
PC5	58	LED6	32
PC4	57	LED5	33
PC3	56	LED4	34
PC2	55	LED3	35
PC1	54	LED2	36
PC0	53	LED1	37

o

Ref	Angle	S_TRIGx		S_ECHOx	IC TRIG	IC ECHO	ARD TRIG	ARD ECHO
N5	0.0	5	5	75	86	25	A11
N6	22.5	6	6	74	87	26	A10
N7	45.0	7	7	73	88	27	A9
N7	67.5	8	8	72	89	28	A8

1. Make sure that Loki wheels turn through RAB (ROS Arduino Bridge) interface. [Done]

2. Make sure that Loki encoders work through RAB. [Done]

3. Tune Loki PID loops so that Loki can be commanded to move at a set speed. [Done]

4. Create a robot launch file that brings up remote control through ROS and a PS3/XBox hand controller. [Mostly Done]

1. Develop a Loki URDF model that specifies the robot dimensions and wheel placement. Origin at robot turn point. [Pending]

2. Develop a Loki URDF model that specifies the Sonar positions and angles. [Done]

3. Develop a Loki URDF model that specifies the RasPi camera location. [Pending]

4. Develop a Loki URDF model that specifies the the MeArm. [Pending]

1. Create robot/rviz launch files that show the sonars working. [Done?]

2. Create robot/rviz launch files that bring up local cost map using sonars [Done?]

1. Ensure that we can read the RasPi camera. [Done]

2. Calibrate the RasPi camera. [Done]

3. Talk with Maxed-Out team about how they talked to RasPi camera [Pending]

1. Verify that we can use the same camera calibration across multiple RasPi cameras [Done?]

2. Integrate RasPi camera with Fiducial Map generator. [Done]

3. Create robot/rviz launch files for creating a Map using RasPi Camera and map generator code. [Done]

4. Create robot/rviz launch model that shows current robot location and pose in rviz. It must update properly when robot is moved by hand. [Pending]

5. Create a test to characterize rolling shutter motion blur as a function of speed. [Pending]

6. Create a work-around to mitigate motion blur issue. [Pending]

1. Create robot/rviz launch files to bring up move_base node with empty obstacle map (i.e. no sonar, just encoders.) Make sure that clicking in rviz cause the robot to move to the desired location. [In Progress]

2. Create robot/rviz launch files to integrate sonars with move_base. [Pending]

3. Bring up local cost map in RViz. [Mostly done; some issues left]

4. Integrate Loki base outline and inflation characteristics into move_base [Pending]

5. Integrate sonars based local cost map together with move_base. The goal here is to go from point to point avoiding obsticles. [Attempted, not much success yet.]

6. Integerate encoders/sonars/fiducials to move_base. [Pending]

1. Bring up servos. [Pending]

2. Bring up move_it node. [Pending]