2009-02-09T06:59:03Z

Hwang:

File:Virtualdub markin.gif

2009-02-09T06:58:48Z

Hwang:

Swarm Robot Project Documentation

2009-02-09T06:56:56Z

Hwang: /* Extracting Frames with VirtualDub */

__TOC__
=Getting Started=
[[Swarm_E-puck_Quickstart_Guide|e-puck Quickstart Guide]]

You can see the official documentation at [http://www.e-puck.org www.e-puck.org] and going to '''Download>Documentation'''.

=e-pucks=
The e-puck is a cylindrical robot from EPFL with a diameter of 70 mm and a height of 53 mm, with a stepper motor driven wheel mounted on each side of the body. The e-puck’s size was ideal for the project, and its stepper motor driven wheels offered consistency and accuracy—highly desirable features for motion planning and dead reckoning. In order to address the requirement for wireless communication, the original extension module on the e-puck which contained peripherals including a speaker, infrared receiver, and mode selection switch, was replaced by a custom-made extension module that held an XBee radio module which connected to the serial port of the microcontroller.

Information about the e-puck can be found at [http://www.e-puck.org/ http://www.e-puck.org/]
==[[Swarm_Project_E-puck_Code|e-puck code]]==
The code on the e-puck was written in C and compiled using Microchip's ''MPLAB C Compiler for dsPIC DSCs'' (student version). The student version can be downloaded from [[http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 Microchip's website.]] When you set up the project, be sure to add the linker library file (libp30F6014A-coff.a) and linker script (p30f6014A.gld) in the project.

Note that the robots will start out in 'sleep' mode. Use the [[Machine_Vision_Localization_System#Commands| 'wake' command]] on the visualization system to start the robots.

The documentation for the code can be found at [[Swarm_Project_E-puck_Code]].

=Packet Structure=
The send and receive packets (for the XBee radios using their proprietary API mode) are different, e.g. the packet received by one PIC is not the exact copy of the packet what was sent out of the other PIC's serial port. The data frame, or payload, is unchanged, although it may be reformatted in the presence of escape characters. See the XBee manual for detailed information on XBee API packets.

==Data Frame==
The data frame of the packet contains the data needed for the swarm consensus estimator, as well as any additional statistics that we may wish to piggyback with the packet (for example, position and orientation data for data logging).

The data frame (in its current state) contains 15 floating point numbers. The contents are as follows:
#x_1
#w_1
#x_2
#w_2
#x_3
#w_3
#x_4
#w_4
#x_5
#w_5
#Robot X coordinate
#Robot Y coordinate
#Robot Theta orientation
#Robot left wheel speed
#Robot right wheel speed

Each number is a 32-bit floating point, which means that the data frame is 60 bytes long, although it could be longer if escape characters are needed (see ''API Operation'' in the XBee Manual).

=XBee Radios=
The XBee radio module is a low-cost, low-power (1mW) radio that uses the IEEE 802.15.4 standard (which specifies the physical layer and medium access control layer of the network) and operates on the 2.4GHz ISM frequency band. Each module contains both a RF transceiver and a microcontroller whose firmware provides a basic implementation of networking capabilities such as addressing, packet, and checksums. The radios together form a peer-to-peer network where each member of the network can broadcast messages to any other member of the network. The XBee module communicates with the PIC microcontroller on the e-puck via the serial port using the RS-232 serial data transfer protocol at 115200 bauds per second.

Due to the robust nature of the swarming algorithm, some packet loss was acceptable; packet recovery schemes were foregone in favor of simplicity and lower power consumption.

==XBee Radio Configuration==
The XBee radio has 20 input/output pins whose signals and functions can be found in section 1.5 in the user’s manual. The only pins that are of particular interest us are:
*Pin 1: 3.3V Power
*Pin 2 (output): UART Data Out
*Pin 3 (input): UART Data In
*Pin 10: Power Ground
*Pin 12 (output): CTS flow control
*Pin 16 (input): RTS flow control

The RTS and CTS signals are for flow control. When the RTS line is pulled low, the XBee module will hold any data waiting to be sent to the microcontroller in a buffer until the line is pulled high again. When the buffer is almost full, the XBee module will pull the CTS signal high.

Details about the XBee radio and its operation can be found in the user’s manual.

'''Also see the [[XBee_radio_communication_between_PICs#Using_the_XBee_Radio|Using the XBee Radio]] page.'''

Two firmware options for the microcontroller are available from Digi. The first option implements a suite of networking capabilities including packets, checksums, addressing, and diagnostics; this implementation is specific to the XBee radios and not compatible with other wireless devices. The second option is a ZigBee protocol stack, which is a mesh networking standard for low data rate networks. Because routing and mesh networking capabilities were not needed for this project, the first option was used for simplicity.

The XBee module can be configured using the X-CTU terminal program from Digi, either by sending commands from the terminal or by using the configuration utility found under the “Modem Configuration” tab. Entering the '''+++''' string into the terminal will make the radio enter command mode. Wait until the XBee return The functions of the commands are described below:

===Configuration for e-puck XBee radios===
For this project, each of the radios on the e-pucks were configured by typing the following commands into the terminal:

<pre>
+++
atre
atmy <ID>
atap 2
atd6 1
atbd 7
atwr
</pre>

where <ID> is an ID number used to differentiate the radios. The firmware on the e-puck requires that the IDs range from 0 to 31. In our case, the XBee radios on the robots were given ID numbers 1 through 8, and the base station radio was given an ID of 0.

===Configuration for base station/data logger XBee radios===
In order to distinguish the radios used by the vision system, real-time display, and data logger, we give them the ID 0 (which means that no robot should have an XBee with ID 0. When a robot received a packet from radio ID 0, then it knows that it is from the vision system computer.). The configuration is the same, except that we do not need flow control, and the ID is always 0.
<pre>
+++
atre
atmy 0
atap 2
atbd 7
atwr
</pre>

{| class="wikitable" border="3"
|+'''XBee AT Commands'''
|-
! Command !! Description
|-
| ATRE || Resets the radio parameters to their factory default.
|-
| ATMY <ID>|| Sets the ID of the radio.
|-
| ATAP 2 || Enables mode 2 of the radio’s API to enable 
advanced features such as packets and addressing
|-
| ATD6 1|| Enables the RTS flow control pin. If this pin is pulled low, 
the XBee will hold bytes to be transmitted to the microcontroller in its buffer.
|-
| ATBD 7 || Sets to baud rate to 115200 bps.
|-
| ATWR|| Writes the new setting to non-volatile memory.
|}

In order for the radios to be able to communicate, they must all be on the same channel and have the same network ID. If the radios experience interference from other XBee radios, the channel or network ID can be changed.

==XBee Interface Extension Board==
The XBee Interface Extension Board was created with Traxmaker. The extension modules plug into the e-puck via [[Media:Samtec BTE-020-02-L-D-A.zip |Samtec BTE-020-02-L-D-A]] connectors, which can be obtained directly from Samtec or one of their distributors. The Traxmaker parts library, which contains the connector and can be downloaded here: [[Media:Traxmaker_XBee_Lbrary.zip]].
===Current Version===
[[Image:e-puck_XBee_board_v1.gif|left|thumb]]
The Traxmaker file for the current version of the XBee extension board can be downloaded here :[[Media:e-puck_xbee_board_v1.PCB]]. Note that the CTS and RTS pins were connected to the sel2 and sel3 pins (instead of y0 and y1) by soldering on jumper wires.

 

===Board In Development===
[[Image:epuck_xbee_board_v2.gif|thumb|left]]A version of the e-puck with a color sensor circuit built in can be downloaded here: [[Media:epuck_xbee_board_v2.PCB]]. This version uses a high-impedance op-amp to amplify signals from three photodiodes (for red, green, and blue), and feeds the outputs into the ADC channels formerly used by the X,Y, and Z axis accelerometers. A 10k potentiometer adjusts the sensitivity for each channel of the amplifier. The RTS flow control line on the XBee is connected to the sel3 line of the e-puck. The CTS line is not hardwired to the sel2 pin, but can easily be connected with a jumper.
 

===Assembling the Boards===
'''Parts:'''
#2x 10 pos. 2 mm pitch socket (Digikey S5751-10-ND)
#LE-33 low dropout voltage regulator (Digikey 497-4258-1-ND)
#2.2uF tantalum capacitor (Digikey 399-3536-ND)
#2x Samtec BTE-020-02-L-D-A (Order directly from Samtec)
#0.1"header pins for RTS and CTS pins (you can also use wire for a permanent connection.
#2x 0.1" jumpers for connecting RTS and CTS pins if you used header pins(Digikey S9000-ND)

=Localization Vision System=
A machine vision system was developed for robot localization, a la GPS. The system uses cameras and pattern recognition algorithms to track the position and orientation of various targets in a workspace, and radios the data to the respective robots. The description of the system can be found at [[Machine_Vision_Localization_System]].

=Simulator=
The simulator attempts to model the robots in MATLAB.
Download the files here: [[Image:swarm_robot_simulation.zip]]

=Analysis Tools=
There are some useful tools that can help you visualize the system, log data, and debug software. They interface with an XBee radio through the serial port, and should be configured like the rest of the radios.
==Real-time Display==
This is a real-time visualization system that displays the state of the system while it is running. It will draw the ellipse representing the target (the black ellipse)It is written in MATLAB. You can get the files here:[[Image:swarm_RT_display.zip]].
# Connect a configured XBee radio to the computer. Be sure to give the radio ID 0. If you are running another program that uses a serial port, such as the vision system, you will have to use another port and XBee radio. Each serial port can only be accessed by one serial port at a time (therefore, you could have multiple radios connected to the same computer).
# Run the <tt>open_serial.m</tt> script after replacing the 'COM1' parameter in the '''initXBeeSerial''' function call with the serial that you are using.
#run the RT_Swarm_Plotter.m script. Hit 'q' to stop the logger. Run the script again if you want to resume.
#run the close_serial.m script to close the serial port when you are done.

==Using the Data Logger with Timestamp==
Download the project here: [[Image:swarm_data_logger.zip]]

This program connects to a configured XBee radio (make sure the ID is 0) at the serial port, and reads and parses any XBee packets it receives. It will output two MATLAB files, <tt>main_log.m</tt> and <tt>run_me.m</tt>. The file <tt>main_log.m</tt> contains all of the information in the received packets with a real-time timestamp (in seconds since the start of the program) added, and the file <tt>run_me.m</tt> contains a short example on how to plot the data.

* '''It is important that you don't close the window while the parser is running, or it will not format the output files property and MATLAB won't be able to read it. To stop logger, press 'a'. This will make it close the files correctly.'''

The <tt>main_log.m</tt> output file, when run, will create several arrays in the work space. It will also have a struct called '''agents''' which contains copies of these arrays--putting them in a struct makes it possible to access the data by manipulating indexes instead of variable names. The vector '''agent_list''' contains the IDs of the agents whose data corresponds to the data in the '''agents''' struct.

==Packet Data Viewer==
Download the project here: [[Image:swarm_packet_data_viewer.zip]]

This program will display the raw data in the packets; it is useful for debugging. Written with VC++.

==Packet Sender==
Download the project here: [[Image:swarm_XBee_packet_sender.zip]]

This program sends out XBee formatted packets in an infinite loop. It is useful for debugging.

=Making Videos with Overlays=
This section explains how to make a video with overlaid figures in MATLAB. To make the video, you'll need the footage, and the output file from the data logger.

You can download the MATLAB files you need here: [[Image:swarm_plotting_files.zip]]

Procedure for Taking the Video:
#Turn on all the robots.
#Start the video camera.
#Turn on and start the data logger.
#Turn on the vision system.
#Send commands to the swarm to change the settings if needed, and send the wake command to start the swarm.
#Send the sleep command the stop the swarm when done.
#Press 'a' at the data logger window to close the file, and 'q' to close the program.
#Turn off the video camera and robots.

Procedure for generating the video:
#Extract the frames of the video with VirtualDub, starting at the moment the robots start moving from the wake command.
#Align the plotting axis and the real-world axis of video in Matlab.
#Run the script to generate the uncompressed video file.
#Compress the video.

==Recording the Data==
To make a video with Matlab plots overlaid on top of the original footage, you need to log the messages from the base station as well as the robots while the video is running. You should start the logger before sending out commands with the vision system, so that the logger can record the commands as well.

==Extracting Frames with VirtualDub==
You can extract the frames from a video with a program called VirtualDub ([http://www.virtualdub.org http://www.virtualdub.org]). VirtualDub is a free video processing program for splitting, compressing, and processing videos.

Install VirtualDub, and open the video recording (VirtualDub can't open all file types, but most .avi or .mpeg files should be fine).

#Move the slider to the frame where the final "wake" command is given (this should be when the robots start moving).
#Click the ''Mark In'' button [[Image:virtualdub_markin.gif]] to indicate the start of the clip.
#Move the slider to where you wish to end the video and click the ''Mark Out'' button [[Image:virtualdub_markout.gif]] to indicate the end.
#Go to '''File>Export>Image Sequence...'''
#Enter ''frame'' for filename, ''.jpeg'' for the filename suffix, and ''1'' for the minimum number of digits.
#Make a folder named "Frames" and set it to be the output directory.
#Select JPEG as the file type, set quality to 100.
#Click OK to start extracting frames.

[[Image:virtualdub_extract_frames.gif]]

==Generating the Video==

==Compressing the Video==

Swarm Robot Project Documentation

2009-02-09T04:02:11Z

Hwang: /* Extracting Frames with VirtualDub */

__TOC__
=Getting Started=
[[Swarm_E-puck_Quickstart_Guide|e-puck Quickstart Guide]]

You can see the official documentation at [http://www.e-puck.org www.e-puck.org] and going to '''Download>Documentation'''.

=e-pucks=
The e-puck is a cylindrical robot from EPFL with a diameter of 70 mm and a height of 53 mm, with a stepper motor driven wheel mounted on each side of the body. The e-puck’s size was ideal for the project, and its stepper motor driven wheels offered consistency and accuracy—highly desirable features for motion planning and dead reckoning. In order to address the requirement for wireless communication, the original extension module on the e-puck which contained peripherals including a speaker, infrared receiver, and mode selection switch, was replaced by a custom-made extension module that held an XBee radio module which connected to the serial port of the microcontroller.

Information about the e-puck can be found at [http://www.e-puck.org/ http://www.e-puck.org/]
==[[Swarm_Project_E-puck_Code|e-puck code]]==
The code on the e-puck was written in C and compiled using Microchip's ''MPLAB C Compiler for dsPIC DSCs'' (student version). The student version can be downloaded from [[http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 Microchip's website.]] When you set up the project, be sure to add the linker library file (libp30F6014A-coff.a) and linker script (p30f6014A.gld) in the project.

Note that the robots will start out in 'sleep' mode. Use the [[Machine_Vision_Localization_System#Commands| 'wake' command]] on the visualization system to start the robots.

The documentation for the code can be found at [[Swarm_Project_E-puck_Code]].

=Packet Structure=
The send and receive packets (for the XBee radios using their proprietary API mode) are different, e.g. the packet received by one PIC is not the exact copy of the packet what was sent out of the other PIC's serial port. The data frame, or payload, is unchanged, although it may be reformatted in the presence of escape characters. See the XBee manual for detailed information on XBee API packets.

==Data Frame==
The data frame of the packet contains the data needed for the swarm consensus estimator, as well as any additional statistics that we may wish to piggyback with the packet (for example, position and orientation data for data logging).

The data frame (in its current state) contains 15 floating point numbers. The contents are as follows:
#x_1
#w_1
#x_2
#w_2
#x_3
#w_3
#x_4
#w_4
#x_5
#w_5
#Robot X coordinate
#Robot Y coordinate
#Robot Theta orientation
#Robot left wheel speed
#Robot right wheel speed

Each number is a 32-bit floating point, which means that the data frame is 60 bytes long, although it could be longer if escape characters are needed (see ''API Operation'' in the XBee Manual).

=XBee Radios=
The XBee radio module is a low-cost, low-power (1mW) radio that uses the IEEE 802.15.4 standard (which specifies the physical layer and medium access control layer of the network) and operates on the 2.4GHz ISM frequency band. Each module contains both a RF transceiver and a microcontroller whose firmware provides a basic implementation of networking capabilities such as addressing, packet, and checksums. The radios together form a peer-to-peer network where each member of the network can broadcast messages to any other member of the network. The XBee module communicates with the PIC microcontroller on the e-puck via the serial port using the RS-232 serial data transfer protocol at 115200 bauds per second.

Due to the robust nature of the swarming algorithm, some packet loss was acceptable; packet recovery schemes were foregone in favor of simplicity and lower power consumption.

==XBee Radio Configuration==
The XBee radio has 20 input/output pins whose signals and functions can be found in section 1.5 in the user’s manual. The only pins that are of particular interest us are:
*Pin 1: 3.3V Power
*Pin 2 (output): UART Data Out
*Pin 3 (input): UART Data In
*Pin 10: Power Ground
*Pin 12 (output): CTS flow control
*Pin 16 (input): RTS flow control

The RTS and CTS signals are for flow control. When the RTS line is pulled low, the XBee module will hold any data waiting to be sent to the microcontroller in a buffer until the line is pulled high again. When the buffer is almost full, the XBee module will pull the CTS signal high.

Details about the XBee radio and its operation can be found in the user’s manual.

'''Also see the [[XBee_radio_communication_between_PICs#Using_the_XBee_Radio|Using the XBee Radio]] page.'''

Two firmware options for the microcontroller are available from Digi. The first option implements a suite of networking capabilities including packets, checksums, addressing, and diagnostics; this implementation is specific to the XBee radios and not compatible with other wireless devices. The second option is a ZigBee protocol stack, which is a mesh networking standard for low data rate networks. Because routing and mesh networking capabilities were not needed for this project, the first option was used for simplicity.

The XBee module can be configured using the X-CTU terminal program from Digi, either by sending commands from the terminal or by using the configuration utility found under the “Modem Configuration” tab. Entering the '''+++''' string into the terminal will make the radio enter command mode. Wait until the XBee return The functions of the commands are described below:

===Configuration for e-puck XBee radios===
For this project, each of the radios on the e-pucks were configured by typing the following commands into the terminal:

<pre>
+++
atre
atmy <ID>
atap 2
atd6 1
atbd 7
atwr
</pre>

where <ID> is an ID number used to differentiate the radios. The firmware on the e-puck requires that the IDs range from 0 to 31. In our case, the XBee radios on the robots were given ID numbers 1 through 8, and the base station radio was given an ID of 0.

===Configuration for base station/data logger XBee radios===
In order to distinguish the radios used by the vision system, real-time display, and data logger, we give them the ID 0 (which means that no robot should have an XBee with ID 0. When a robot received a packet from radio ID 0, then it knows that it is from the vision system computer.). The configuration is the same, except that we do not need flow control, and the ID is always 0.
<pre>
+++
atre
atmy 0
atap 2
atbd 7
atwr
</pre>

{| class="wikitable" border="3"
|+'''XBee AT Commands'''
|-
! Command !! Description
|-
| ATRE || Resets the radio parameters to their factory default.
|-
| ATMY <ID>|| Sets the ID of the radio.
|-
| ATAP 2 || Enables mode 2 of the radio’s API to enable 
advanced features such as packets and addressing
|-
| ATD6 1|| Enables the RTS flow control pin. If this pin is pulled low, 
the XBee will hold bytes to be transmitted to the microcontroller in its buffer.
|-
| ATBD 7 || Sets to baud rate to 115200 bps.
|-
| ATWR|| Writes the new setting to non-volatile memory.
|}

In order for the radios to be able to communicate, they must all be on the same channel and have the same network ID. If the radios experience interference from other XBee radios, the channel or network ID can be changed.

==XBee Interface Extension Board==
The XBee Interface Extension Board was created with Traxmaker. The extension modules plug into the e-puck via [[Media:Samtec BTE-020-02-L-D-A.zip |Samtec BTE-020-02-L-D-A]] connectors, which can be obtained directly from Samtec or one of their distributors. The Traxmaker parts library, which contains the connector and can be downloaded here: [[Media:Traxmaker_XBee_Lbrary.zip]].
===Current Version===
[[Image:e-puck_XBee_board_v1.gif|left|thumb]]
The Traxmaker file for the current version of the XBee extension board can be downloaded here :[[Media:e-puck_xbee_board_v1.PCB]]. Note that the CTS and RTS pins were connected to the sel2 and sel3 pins (instead of y0 and y1) by soldering on jumper wires.

 

===Board In Development===
[[Image:epuck_xbee_board_v2.gif|thumb|left]]A version of the e-puck with a color sensor circuit built in can be downloaded here: [[Media:epuck_xbee_board_v2.PCB]]. This version uses a high-impedance op-amp to amplify signals from three photodiodes (for red, green, and blue), and feeds the outputs into the ADC channels formerly used by the X,Y, and Z axis accelerometers. A 10k potentiometer adjusts the sensitivity for each channel of the amplifier. The RTS flow control line on the XBee is connected to the sel3 line of the e-puck. The CTS line is not hardwired to the sel2 pin, but can easily be connected with a jumper.
 

===Assembling the Boards===
'''Parts:'''
#2x 10 pos. 2 mm pitch socket (Digikey S5751-10-ND)
#LE-33 low dropout voltage regulator (Digikey 497-4258-1-ND)
#2.2uF tantalum capacitor (Digikey 399-3536-ND)
#2x Samtec BTE-020-02-L-D-A (Order directly from Samtec)
#0.1"header pins for RTS and CTS pins (you can also use wire for a permanent connection.
#2x 0.1" jumpers for connecting RTS and CTS pins if you used header pins(Digikey S9000-ND)

=Localization Vision System=
A machine vision system was developed for robot localization, a la GPS. The system uses cameras and pattern recognition algorithms to track the position and orientation of various targets in a workspace, and radios the data to the respective robots. The description of the system can be found at [[Machine_Vision_Localization_System]].

=Simulator=
The simulator attempts to model the robots in MATLAB.
Download the files here: [[Image:swarm_robot_simulation.zip]]

=Analysis Tools=
There are some useful tools that can help you visualize the system, log data, and debug software. They interface with an XBee radio through the serial port, and should be configured like the rest of the radios.
==Real-time Display==
This is a real-time visualization system that displays the state of the system while it is running. It will draw the ellipse representing the target (the black ellipse)It is written in MATLAB. You can get the files here:[[Image:swarm_RT_display.zip]].
# Connect a configured XBee radio to the computer. Be sure to give the radio ID 0. If you are running another program that uses a serial port, such as the vision system, you will have to use another port and XBee radio. Each serial port can only be accessed by one serial port at a time (therefore, you could have multiple radios connected to the same computer).
# Run the <tt>open_serial.m</tt> script after replacing the 'COM1' parameter in the '''initXBeeSerial''' function call with the serial that you are using.
#run the RT_Swarm_Plotter.m script. Hit 'q' to stop the logger. Run the script again if you want to resume.
#run the close_serial.m script to close the serial port when you are done.

==Using the Data Logger with Timestamp==
Download the project here: [[Image:swarm_data_logger.zip]]

This program connects to a configured XBee radio (make sure the ID is 0) at the serial port, and reads and parses any XBee packets it receives. It will output two MATLAB files, <tt>main_log.m</tt> and <tt>run_me.m</tt>. The file <tt>main_log.m</tt> contains all of the information in the received packets with a real-time timestamp (in seconds since the start of the program) added, and the file <tt>run_me.m</tt> contains a short example on how to plot the data.

* '''It is important that you don't close the window while the parser is running, or it will not format the output files property and MATLAB won't be able to read it. To stop logger, press 'a'. This will make it close the files correctly.'''

The <tt>main_log.m</tt> output file, when run, will create several arrays in the work space. It will also have a struct called '''agents''' which contains copies of these arrays--putting them in a struct makes it possible to access the data by manipulating indexes instead of variable names. The vector '''agent_list''' contains the IDs of the agents whose data corresponds to the data in the '''agents''' struct.

==Packet Data Viewer==
Download the project here: [[Image:swarm_packet_data_viewer.zip]]

This program will display the raw data in the packets; it is useful for debugging. Written with VC++.

==Packet Sender==
Download the project here: [[Image:swarm_XBee_packet_sender.zip]]

This program sends out XBee formatted packets in an infinite loop. It is useful for debugging.

=Making Videos with Overlays=
This section explains how to make a video with overlaid figures in MATLAB. To make the video, you'll need the footage, and the output file from the data logger.

You can download the MATLAB files you need here: [[Image:swarm_plotting_files.zip]]

Procedure for Taking the Video:
#Turn on all the robots.
#Start the video camera.
#Turn on and start the data logger.
#Turn on the vision system.
#Send commands to the swarm to change the settings if needed, and send the wake command to start the swarm.
#Send the sleep command the stop the swarm when done.
#Press 'a' at the data logger window to close the file, and 'q' to close the program.
#Turn off the video camera and robots.

Procedure for generating the video:
#Extract the frames of the video with VirtualDub, starting at the moment the robots start moving from the wake command.
#Align the plotting axis and the real-world axis of video in Matlab.
#Run the script to generate the uncompressed video file.
#Compress the video.

==Recording the Data==
To make a video with Matlab plots overlaid on top of the original footage, you need to log the messages from the base station as well as the robots while the video is running. You should start the logger before sending out commands with the vision system, so that the logger can record the commands as well.

==Extracting Frames with VirtualDub==
You can extract the frames from a video with a program called VirtualDub ([http://www.virtualdub.org http://www.virtualdub.org]). VirtualDub is a free video processing program for splitting, compressing, and processing videos.

==Generating the Video==

==Compressing the Video==

File:Swarm robot simulation.zip

2009-02-04T04:45:44Z

Hwang:

Swarm Robot Project Documentation

2009-02-03T06:34:04Z

Hwang: /* Making Videos with Overlays */

__TOC__
=Getting Started=
[[Swarm_E-puck_Quickstart_Guide|e-puck Quickstart Guide]]

You can see the official documentation at [http://www.e-puck.org www.e-puck.org] and going to '''Download>Documentation'''.

=e-pucks=
The e-puck is a cylindrical robot from EPFL with a diameter of 70 mm and a height of 53 mm, with a stepper motor driven wheel mounted on each side of the body. The e-puck’s size was ideal for the project, and its stepper motor driven wheels offered consistency and accuracy—highly desirable features for motion planning and dead reckoning. In order to address the requirement for wireless communication, the original extension module on the e-puck which contained peripherals including a speaker, infrared receiver, and mode selection switch, was replaced by a custom-made extension module that held an XBee radio module which connected to the serial port of the microcontroller.

Information about the e-puck can be found at [http://www.e-puck.org/ http://www.e-puck.org/]
==[[Swarm_Project_E-puck_Code|e-puck code]]==
The code on the e-puck was written in C and compiled using Microchip's ''MPLAB C Compiler for dsPIC DSCs'' (student version). The student version can be downloaded from [[http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 Microchip's website.]] When you set up the project, be sure to add the linker library file (libp30F6014A-coff.a) and linker script (p30f6014A.gld) in the project.

Note that the robots will start out in 'sleep' mode. Use the [[Machine_Vision_Localization_System#Commands| 'wake' command]] on the visualization system to start the robots.

The documentation for the code can be found at [[Swarm_Project_E-puck_Code]].

=Packet Structure=
The send and receive packets (for the XBee radios using their proprietary API mode) are different, e.g. the packet received by one PIC is not the exact copy of the packet what was sent out of the other PIC's serial port. The data frame, or payload, is unchanged, although it may be reformatted in the presence of escape characters. See the XBee manual for detailed information on XBee API packets.

==Data Frame==
The data frame of the packet contains the data needed for the swarm consensus estimator, as well as any additional statistics that we may wish to piggyback with the packet (for example, position and orientation data for data logging).

The data frame (in its current state) contains 15 floating point numbers. The contents are as follows:
#x_1
#w_1
#x_2
#w_2
#x_3
#w_3
#x_4
#w_4
#x_5
#w_5
#Robot X coordinate
#Robot Y coordinate
#Robot Theta orientation
#Robot left wheel speed
#Robot right wheel speed

Each number is a 32-bit floating point, which means that the data frame is 60 bytes long, although it could be longer if escape characters are needed (see ''API Operation'' in the XBee Manual).

=XBee Radios=
The XBee radio module is a low-cost, low-power (1mW) radio that uses the IEEE 802.15.4 standard (which specifies the physical layer and medium access control layer of the network) and operates on the 2.4GHz ISM frequency band. Each module contains both a RF transceiver and a microcontroller whose firmware provides a basic implementation of networking capabilities such as addressing, packet, and checksums. The radios together form a peer-to-peer network where each member of the network can broadcast messages to any other member of the network. The XBee module communicates with the PIC microcontroller on the e-puck via the serial port using the RS-232 serial data transfer protocol at 115200 bauds per second.

Due to the robust nature of the swarming algorithm, some packet loss was acceptable; packet recovery schemes were foregone in favor of simplicity and lower power consumption.

==XBee Radio Configuration==
The XBee radio has 20 input/output pins whose signals and functions can be found in section 1.5 in the user’s manual. The only pins that are of particular interest us are:
*Pin 1: 3.3V Power
*Pin 2 (output): UART Data Out
*Pin 3 (input): UART Data In
*Pin 10: Power Ground
*Pin 12 (output): CTS flow control
*Pin 16 (input): RTS flow control

The RTS and CTS signals are for flow control. When the RTS line is pulled low, the XBee module will hold any data waiting to be sent to the microcontroller in a buffer until the line is pulled high again. When the buffer is almost full, the XBee module will pull the CTS signal high.

Details about the XBee radio and its operation can be found in the user’s manual.

'''Also see the [[XBee_radio_communication_between_PICs#Using_the_XBee_Radio|Using the XBee Radio]] page.'''

Two firmware options for the microcontroller are available from Digi. The first option implements a suite of networking capabilities including packets, checksums, addressing, and diagnostics; this implementation is specific to the XBee radios and not compatible with other wireless devices. The second option is a ZigBee protocol stack, which is a mesh networking standard for low data rate networks. Because routing and mesh networking capabilities were not needed for this project, the first option was used for simplicity.

The XBee module can be configured using the X-CTU terminal program from Digi, either by sending commands from the terminal or by using the configuration utility found under the “Modem Configuration” tab. Entering the '''+++''' string into the terminal will make the radio enter command mode. Wait until the XBee return The functions of the commands are described below:

===Configuration for e-puck XBee radios===
For this project, each of the radios on the e-pucks were configured by typing the following commands into the terminal:

<pre>
+++
atre
atmy <ID>
atap 2
atd6 1
atbd 7
atwr
</pre>

where <ID> is an ID number used to differentiate the radios. The firmware on the e-puck requires that the IDs range from 0 to 31. In our case, the XBee radios on the robots were given ID numbers 1 through 8, and the base station radio was given an ID of 0.

===Configuration for base station/data logger XBee radios===
In order to distinguish the radios used by the vision system, real-time display, and data logger, we give them the ID 0 (which means that no robot should have an XBee with ID 0. When a robot received a packet from radio ID 0, then it knows that it is from the vision system computer.). The configuration is the same, except that we do not need flow control, and the ID is always 0.
<pre>
+++
atre
atmy 0
atap 2
atbd 7
atwr
</pre>

{| class="wikitable" border="3"
|+'''XBee AT Commands'''
|-
! Command !! Description
|-
| ATRE || Resets the radio parameters to their factory default.
|-
| ATMY <ID>|| Sets the ID of the radio.
|-
| ATAP 2 || Enables mode 2 of the radio’s API to enable 
advanced features such as packets and addressing
|-
| ATD6 1|| Enables the RTS flow control pin. If this pin is pulled low, 
the XBee will hold bytes to be transmitted to the microcontroller in its buffer.
|-
| ATBD 7 || Sets to baud rate to 115200 bps.
|-
| ATWR|| Writes the new setting to non-volatile memory.
|}

In order for the radios to be able to communicate, they must all be on the same channel and have the same network ID. If the radios experience interference from other XBee radios, the channel or network ID can be changed.

==XBee Interface Extension Board==
The XBee Interface Extension Board was created with Traxmaker. The extension modules plug into the e-puck via [[Media:Samtec BTE-020-02-L-D-A.zip |Samtec BTE-020-02-L-D-A]] connectors, which can be obtained directly from Samtec or one of their distributors. The Traxmaker parts library, which contains the connector and can be downloaded here: [[Media:Traxmaker_XBee_Lbrary.zip]].
===Current Version===
[[Image:e-puck_XBee_board_v1.gif|left|thumb]]
The Traxmaker file for the current version of the XBee extension board can be downloaded here :[[Media:e-puck_xbee_board_v1.PCB]]. Note that the CTS and RTS pins were connected to the sel2 and sel3 pins (instead of y0 and y1) by soldering on jumper wires.

 

===Board In Development===
[[Image:epuck_xbee_board_v2.gif|thumb|left]]A version of the e-puck with a color sensor circuit built in can be downloaded here: [[Media:epuck_xbee_board_v2.PCB]]. This version uses a high-impedance op-amp to amplify signals from three photodiodes (for red, green, and blue), and feeds the outputs into the ADC channels formerly used by the X,Y, and Z axis accelerometers. A 10k potentiometer adjusts the sensitivity for each channel of the amplifier. The RTS flow control line on the XBee is connected to the sel3 line of the e-puck. The CTS line is not hardwired to the sel2 pin, but can easily be connected with a jumper.
 

===Assembling the Boards===
'''Parts:'''
#2x 10 pos. 2 mm pitch socket (Digikey S5751-10-ND)
#LE-33 low dropout voltage regulator (Digikey 497-4258-1-ND)
#2.2uF tantalum capacitor (Digikey 399-3536-ND)
#2x Samtec BTE-020-02-L-D-A (Order directly from Samtec)
#0.1"header pins for RTS and CTS pins (you can also use wire for a permanent connection.
#2x 0.1" jumpers for connecting RTS and CTS pins if you used header pins(Digikey S9000-ND)

=Localization Vision System=
A machine vision system was developed for robot localization, a la GPS. The system uses cameras and pattern recognition algorithms to track the position and orientation of various targets in a workspace, and radios the data to the respective robots. The description of the system can be found at [[Machine_Vision_Localization_System]].

=Simulator=
The simulator attempts to model the robots in MATLAB.
Download the files here: [[Image:swarm_robot_simulation.zip]]

=Analysis Tools=
There are some useful tools that can help you visualize the system, log data, and debug software. They interface with an XBee radio through the serial port, and should be configured like the rest of the radios.
==Real-time Display==
This is a real-time visualization system that displays the state of the system while it is running. It will draw the ellipse representing the target (the black ellipse)It is written in MATLAB. You can get the files here:[[Image:swarm_RT_display.zip]].
# Connect a configured XBee radio to the computer. Be sure to give the radio ID 0. If you are running another program that uses a serial port, such as the vision system, you will have to use another port and XBee radio. Each serial port can only be accessed by one serial port at a time (therefore, you could have multiple radios connected to the same computer).
# Run the <tt>open_serial.m</tt> script after replacing the 'COM1' parameter in the '''initXBeeSerial''' function call with the serial that you are using.
#run the RT_Swarm_Plotter.m script. Hit 'q' to stop the logger. Run the script again if you want to resume.
#run the close_serial.m script to close the serial port when you are done.

==Using the Data Logger with Timestamp==
Download the project here: [[Image:swarm_data_logger.zip]]

This program connects to a configured XBee radio (make sure the ID is 0) at the serial port, and reads and parses any XBee packets it receives. It will output two MATLAB files, <tt>main_log.m</tt> and <tt>run_me.m</tt>. The file <tt>main_log.m</tt> contains all of the information in the received packets with a real-time timestamp (in seconds since the start of the program) added, and the file <tt>run_me.m</tt> contains a short example on how to plot the data.

* '''It is important that you don't close the window while the parser is running, or it will not format the output files property and MATLAB won't be able to read it. To stop logger, press 'a'. This will make it close the files correctly.'''

The <tt>main_log.m</tt> output file, when run, will create several arrays in the work space. It will also have a struct called '''agents''' which contains copies of these arrays--putting them in a struct makes it possible to access the data by manipulating indexes instead of variable names. The vector '''agent_list''' contains the IDs of the agents whose data corresponds to the data in the '''agents''' struct.

==Packet Data Viewer==
Download the project here: [[Image:swarm_packet_data_viewer.zip]]

This program will display the raw data in the packets; it is useful for debugging. Written with VC++.

==Packet Sender==
Download the project here: [[Image:swarm_XBee_packet_sender.zip]]

This program sends out XBee formatted packets in an infinite loop. It is useful for debugging.

=Making Videos with Overlays=
This section explains how to make a video with overlaid figures in MATLAB. To make the video, you'll need the footage, and the output file from the data logger.

You can download the MATLAB files you need here: [[Image:swarm_plotting_files.zip]]

Procedure for Taking the Video:
#Turn on all the robots.
#Start the video camera.
#Turn on and start the data logger.
#Turn on the vision system.
#Send commands to the swarm to change the settings if needed, and send the wake command to start the swarm.
#Send the sleep command the stop the swarm when done.
#Press 'a' at the data logger window to close the file, and 'q' to close the program.
#Turn off the video camera and robots.

Procedure for generating the video:
#Extract the frames of the video with VirtualDub, starting at the moment the robots start moving from the wake command.
#Align the plotting axis and the real-world axis of video in Matlab.
#Run the script to generate the uncompressed video file.
#Compress the video.

==Recording the Data==
To make a video with Matlab plots overlaid on top of the original footage, you need to log the messages from the base station as well as the robots while the video is running. You should start the logger before sending out commands with the vision system, so that the logger can record the commands as well.

==Extracting Frames with VirtualDub==

==Generating the Video==

==Compressing the Video==

Swarm Robot Project Documentation

2009-02-03T04:27:14Z

Hwang: /* Recording the Data */

File:Swarm plotting files.zip

2009-01-30T05:02:52Z

Hwang:

Swarm Robot Project Documentation

2009-01-30T04:58:46Z

Hwang: /* Compressing the Video */

Swarm Robot Project Documentation

2009-01-30T04:58:35Z

Hwang: /* Generating the Video */

Swarm Robot Project Documentation

2009-01-30T04:58:24Z

Hwang: /* Extracting Frames with VirtualDub */

Swarm Robot Project Documentation

2009-01-30T04:58:16Z

Hwang: /* Recording the Data */

Swarm Robot Project Documentation

2009-01-30T04:57:55Z

Hwang: /* Making Videos with Overlays */

Swarm Robot Project Documentation

2009-01-30T04:56:43Z

Hwang: /* Making Videos */

Swarm Robot Quickstart Guide

2009-01-29T02:53:45Z

Hwang: /* Starting the Vision System */

__TOC__
This guide was written as a quickstart guide for the Swarm Robots Project, but contains general information about programming e-pucks.
=Checklist=
In order to run the system, you will need:
# e-puck robots, with XBee extension boards and [[Swarm_Robot_Project_Documentation#XBee_Radios|configured radios]].
# Bluetooth adapter on your computer, either internal or an external one such as the D-link DBT-120.
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Compiled .hex file found in e-puck code project]
# [http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm Tiny Bootloader]
# [[Machine_Vision_Localization_System|Compiled program for Machine Vision Localization System]].
# You may also want to use one or more of the [[#Analysis_Tools|Analysis Tools]] such as the real-time display.

==Items needed to edit the e-puck code==
If you want to edit the e-puck code, you will need the following:
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] (for editing code, not needed to run)
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 C compiler for dsPICs] (for editing code, not needed to run)
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Code for e-pucks]

===Compiling the project===
To open the project, extract the directory and double-click on the '''<tt>.mcp</tt>''' file; this is the project file. Because the directory it is in is probably different from the original directory from the computer on which the code was written, you may need to remove and re-add the sources, library, and/or linker files to the project. The source files are in the '''source''' folder. The library and linker files are in the Microhip compiler's install directory(try searching for <tt>libp30F6014A-coff.a</tt> and <tt>p30f6014A.gld</tt>). Press f10 to compile the program. This should generate a .hex file, which is the binary file that you will load onto the e-Puck.

=Programming the e-pucks=
You will need to get the compiled .hex file for the e-puck, and then load it onto the PIC with Tiny Bootloader over the bluetooth radio. The compiled .hex file can be found here: [[Image:Swarm_epucks_code.zip]].
==Connecting to the e-puck==
To program the e-puck, you first need to connect to the e-puck. Go to the Control Panel, and open Bluetooth Devices, and go to '''Devices>Add...'''. Turn on the e-puck, check '''My device is set up and ready to be found''', then click next. When the computer has found the e-puck, select it (the ID of the epuck is a four-digit number found on a sticker on top of the bluetooth chip on the e-puck). When the prompt asks you for a passkey, enter the 4-digit ID number. The computer should then reserve a COM (serial) port to communicate with this particular e-puck. The computer will set up different COM ports for different e-pucks; this is normal. Go back to Bluetooth Devices in the Control Panel, and select the COM Ports tab, and see port is assigned '''Outgoing''' to the e-puck. This is the COM port you will use to program this particular e-puck when using Tiny Bootloader. '''If you're using a USB bluetooth dongle, if you unplug it and replug it into a different USB port, or use a different dongle, you may need to reconnect to the e-pucks.'''

[[Image:BT_COM_ports.png]]

==Programming the e-puck==
A bootloader is a type of program that is loaded onto a microcontroller which allows one to re-program the microcontroller in the field without having to use an special flash programmer (the programmer is still needed to load the bootloader onto the microcontroller in the first place). The Bootloader has two components: a programmer that runs on your computer, and a program that runs on the e-puck's PIC. When the PIC is turned on, bootloader will check to see if someone is attempting to re-program the PIC; if yes, the bootloader will overwrite its old program with the new program; if not, or if it times out while waiting for the new data stream, it will simply run the current program.

To program the e-puck, start the Tiny Bootloader program on your computer. (Although you can also use a flash programmer such as the ICD2 to program the e-puck, it will take much longer and can't be done wirelessly.) Click on '''Browse''' and select the .hex file that you want to load. The .hex file is the compiled code from Microchip's C compiler. Under '''Comm''', use 115200 for the baud rate, and type in the outgoing COM port assigned to this e-puck (e.g. COM10, COM11, etc.). Turn on the e-puck, and click on the Write Flash button. The blue bar underneath the button should start counting down. Now, hit the blue reset button on the e-puck, before the blue bar reaches zero and times out. If the e-puck is successfully connected, an orange LED on the e-puck will turn on, and the bootloader will start to program the PIC on the e-puck.

===Troubleshooting===
* If Tiny Bootloader cannot connect to the COM port, make sure your e-puck is on, and that you've selected the correct COM port assigned to the e-puck (the ID of the e-puck is on a sticker on top of the bluetooth chip on the e-puck's PCB.
* If Tiny Bootloader can connect to the e-puck but cannot find the PIC, it may be that someone has overwritten the bootloader with another program. See the section below [[#Re-loading the Bootloader|Re-loading the Bootloader]] to see how to restore the bootloader with the ICD2 programmer and MPLAB.

====Re-loading the Bootloader====
The e-pucks require that a special bootloader program be loaded on it if you want to program the e-puck over a bluetooth radio.

You can download the .hex file you need at [http://www.e-puck.org http://www.e-puck.org]. On the website, go to Download>Software>Library and download the zip file. Extract the archive, and navigate to '''e-puck-lib\tool\bootloader\epuck_side'''. The file <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt> is the one we will use.

You will need Microchip's [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] and ICD2 to program in the bootloader on the PIC. After opening MPLAB, select to '''Programmer>Select Programmer>ICD2'''. Then, go to '''File>Import>''' and navigate to <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt>. Then, connect to the ICD and program the PIC.

=Starting the Vision System=
The vision system is needed to track the position of the robots and send out commands. You can get the compiled program here:[[Image:vision_system_localization_project.zip]]
# Connect an XBee radio with ID 0 to the computer. The ID must be 0 so that the robots can tell that the packet is from the computer and not another robot.
# Follow the directions on the [[Machine_Vision_Localization_System#Operation | Machine Vision Localization]] page to set up and calibrate the system.
# Make sure the robots are in the field of view of the vision system.
# Let the system run for a few seconds so that the robot's positions will be updated.
# Select the GUI window and hit 'c' to enter the command mode.
# Select the console window and enter the goal statistics that you want using the '''goal''' command. You can skip this step if you want to use the default [100 300 160000 40000 40000] goal statistics. Send the command 2 or three times in case one or more of the robots doesn't get the message.
# Use the '''wake''' command (<tt>wake 0</tt>) to start the robots.
# Exit the console by typing <tt>exit</tt>. The system should now be running.

Try moving the swarm to another configuration:
#press 'c' at the GUI window.
#enter the command <tt>goal 0 -100 -200 120000 0 120000 </tt>
#type <tt>exit</tt> and hit enter.

=Using the Real-Time Display=
See [[Swarm_Robot_Project_Documentation#Real-time_Display]]

=Using the Packet Parser with Timestamp=
See [[Swarm_Robot_Project_Documentation#Using_the_Data_Logger_with_Timestamp]]

Swarm Robot Quickstart Guide

2009-01-29T02:53:37Z

Hwang: /* Starting the Vision System */

__TOC__
This guide was written as a quickstart guide for the Swarm Robots Project, but contains general information about programming e-pucks.
=Checklist=
In order to run the system, you will need:
# e-puck robots, with XBee extension boards and [[Swarm_Robot_Project_Documentation#XBee_Radios|configured radios]].
# Bluetooth adapter on your computer, either internal or an external one such as the D-link DBT-120.
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Compiled .hex file found in e-puck code project]
# [http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm Tiny Bootloader]
# [[Machine_Vision_Localization_System|Compiled program for Machine Vision Localization System]].
# You may also want to use one or more of the [[#Analysis_Tools|Analysis Tools]] such as the real-time display.

==Items needed to edit the e-puck code==
If you want to edit the e-puck code, you will need the following:
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] (for editing code, not needed to run)
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 C compiler for dsPICs] (for editing code, not needed to run)
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Code for e-pucks]

===Compiling the project===
To open the project, extract the directory and double-click on the '''<tt>.mcp</tt>''' file; this is the project file. Because the directory it is in is probably different from the original directory from the computer on which the code was written, you may need to remove and re-add the sources, library, and/or linker files to the project. The source files are in the '''source''' folder. The library and linker files are in the Microhip compiler's install directory(try searching for <tt>libp30F6014A-coff.a</tt> and <tt>p30f6014A.gld</tt>). Press f10 to compile the program. This should generate a .hex file, which is the binary file that you will load onto the e-Puck.

=Programming the e-pucks=
You will need to get the compiled .hex file for the e-puck, and then load it onto the PIC with Tiny Bootloader over the bluetooth radio. The compiled .hex file can be found here: [[Image:Swarm_epucks_code.zip]].
==Connecting to the e-puck==
To program the e-puck, you first need to connect to the e-puck. Go to the Control Panel, and open Bluetooth Devices, and go to '''Devices>Add...'''. Turn on the e-puck, check '''My device is set up and ready to be found''', then click next. When the computer has found the e-puck, select it (the ID of the epuck is a four-digit number found on a sticker on top of the bluetooth chip on the e-puck). When the prompt asks you for a passkey, enter the 4-digit ID number. The computer should then reserve a COM (serial) port to communicate with this particular e-puck. The computer will set up different COM ports for different e-pucks; this is normal. Go back to Bluetooth Devices in the Control Panel, and select the COM Ports tab, and see port is assigned '''Outgoing''' to the e-puck. This is the COM port you will use to program this particular e-puck when using Tiny Bootloader. '''If you're using a USB bluetooth dongle, if you unplug it and replug it into a different USB port, or use a different dongle, you may need to reconnect to the e-pucks.'''

[[Image:BT_COM_ports.png]]

==Programming the e-puck==
A bootloader is a type of program that is loaded onto a microcontroller which allows one to re-program the microcontroller in the field without having to use an special flash programmer (the programmer is still needed to load the bootloader onto the microcontroller in the first place). The Bootloader has two components: a programmer that runs on your computer, and a program that runs on the e-puck's PIC. When the PIC is turned on, bootloader will check to see if someone is attempting to re-program the PIC; if yes, the bootloader will overwrite its old program with the new program; if not, or if it times out while waiting for the new data stream, it will simply run the current program.

To program the e-puck, start the Tiny Bootloader program on your computer. (Although you can also use a flash programmer such as the ICD2 to program the e-puck, it will take much longer and can't be done wirelessly.) Click on '''Browse''' and select the .hex file that you want to load. The .hex file is the compiled code from Microchip's C compiler. Under '''Comm''', use 115200 for the baud rate, and type in the outgoing COM port assigned to this e-puck (e.g. COM10, COM11, etc.). Turn on the e-puck, and click on the Write Flash button. The blue bar underneath the button should start counting down. Now, hit the blue reset button on the e-puck, before the blue bar reaches zero and times out. If the e-puck is successfully connected, an orange LED on the e-puck will turn on, and the bootloader will start to program the PIC on the e-puck.

===Troubleshooting===
* If Tiny Bootloader cannot connect to the COM port, make sure your e-puck is on, and that you've selected the correct COM port assigned to the e-puck (the ID of the e-puck is on a sticker on top of the bluetooth chip on the e-puck's PCB.
* If Tiny Bootloader can connect to the e-puck but cannot find the PIC, it may be that someone has overwritten the bootloader with another program. See the section below [[#Re-loading the Bootloader|Re-loading the Bootloader]] to see how to restore the bootloader with the ICD2 programmer and MPLAB.

====Re-loading the Bootloader====
The e-pucks require that a special bootloader program be loaded on it if you want to program the e-puck over a bluetooth radio.

You can download the .hex file you need at [http://www.e-puck.org http://www.e-puck.org]. On the website, go to Download>Software>Library and download the zip file. Extract the archive, and navigate to '''e-puck-lib\tool\bootloader\epuck_side'''. The file <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt> is the one we will use.

You will need Microchip's [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] and ICD2 to program in the bootloader on the PIC. After opening MPLAB, select to '''Programmer>Select Programmer>ICD2'''. Then, go to '''File>Import>''' and navigate to <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt>. Then, connect to the ICD and program the PIC.

=Starting the Vision System=
The vision system is needed to track the position of the robots and send out commands. You can get the compiled program here:[[Image:vision_system_localization_project.zip]
# Connect an XBee radio with ID 0 to the computer. The ID must be 0 so that the robots can tell that the packet is from the computer and not another robot.
# Follow the directions on the [[Machine_Vision_Localization_System#Operation | Machine Vision Localization]] page to set up and calibrate the system.
# Make sure the robots are in the field of view of the vision system.
# Let the system run for a few seconds so that the robot's positions will be updated.
# Select the GUI window and hit 'c' to enter the command mode.
# Select the console window and enter the goal statistics that you want using the '''goal''' command. You can skip this step if you want to use the default [100 300 160000 40000 40000] goal statistics. Send the command 2 or three times in case one or more of the robots doesn't get the message.
# Use the '''wake''' command (<tt>wake 0</tt>) to start the robots.
# Exit the console by typing <tt>exit</tt>. The system should now be running.

Try moving the swarm to another configuration:
#press 'c' at the GUI window.
#enter the command <tt>goal 0 -100 -200 120000 0 120000 </tt>
#type <tt>exit</tt> and hit enter.

=Using the Real-Time Display=
See [[Swarm_Robot_Project_Documentation#Real-time_Display]]

=Using the Packet Parser with Timestamp=
See [[Swarm_Robot_Project_Documentation#Using_the_Data_Logger_with_Timestamp]]

Swarm Robot Quickstart Guide

2009-01-29T02:53:23Z

Hwang: /* Starting the Vision System */

__TOC__
This guide was written as a quickstart guide for the Swarm Robots Project, but contains general information about programming e-pucks.
=Checklist=
In order to run the system, you will need:
# e-puck robots, with XBee extension boards and [[Swarm_Robot_Project_Documentation#XBee_Radios|configured radios]].
# Bluetooth adapter on your computer, either internal or an external one such as the D-link DBT-120.
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Compiled .hex file found in e-puck code project]
# [http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm Tiny Bootloader]
# [[Machine_Vision_Localization_System|Compiled program for Machine Vision Localization System]].
# You may also want to use one or more of the [[#Analysis_Tools|Analysis Tools]] such as the real-time display.

==Items needed to edit the e-puck code==
If you want to edit the e-puck code, you will need the following:
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] (for editing code, not needed to run)
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 C compiler for dsPICs] (for editing code, not needed to run)
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Code for e-pucks]

===Compiling the project===
To open the project, extract the directory and double-click on the '''<tt>.mcp</tt>''' file; this is the project file. Because the directory it is in is probably different from the original directory from the computer on which the code was written, you may need to remove and re-add the sources, library, and/or linker files to the project. The source files are in the '''source''' folder. The library and linker files are in the Microhip compiler's install directory(try searching for <tt>libp30F6014A-coff.a</tt> and <tt>p30f6014A.gld</tt>). Press f10 to compile the program. This should generate a .hex file, which is the binary file that you will load onto the e-Puck.

=Programming the e-pucks=
You will need to get the compiled .hex file for the e-puck, and then load it onto the PIC with Tiny Bootloader over the bluetooth radio. The compiled .hex file can be found here: [[Image:Swarm_epucks_code.zip]].
==Connecting to the e-puck==
To program the e-puck, you first need to connect to the e-puck. Go to the Control Panel, and open Bluetooth Devices, and go to '''Devices>Add...'''. Turn on the e-puck, check '''My device is set up and ready to be found''', then click next. When the computer has found the e-puck, select it (the ID of the epuck is a four-digit number found on a sticker on top of the bluetooth chip on the e-puck). When the prompt asks you for a passkey, enter the 4-digit ID number. The computer should then reserve a COM (serial) port to communicate with this particular e-puck. The computer will set up different COM ports for different e-pucks; this is normal. Go back to Bluetooth Devices in the Control Panel, and select the COM Ports tab, and see port is assigned '''Outgoing''' to the e-puck. This is the COM port you will use to program this particular e-puck when using Tiny Bootloader. '''If you're using a USB bluetooth dongle, if you unplug it and replug it into a different USB port, or use a different dongle, you may need to reconnect to the e-pucks.'''

[[Image:BT_COM_ports.png]]

==Programming the e-puck==
A bootloader is a type of program that is loaded onto a microcontroller which allows one to re-program the microcontroller in the field without having to use an special flash programmer (the programmer is still needed to load the bootloader onto the microcontroller in the first place). The Bootloader has two components: a programmer that runs on your computer, and a program that runs on the e-puck's PIC. When the PIC is turned on, bootloader will check to see if someone is attempting to re-program the PIC; if yes, the bootloader will overwrite its old program with the new program; if not, or if it times out while waiting for the new data stream, it will simply run the current program.

To program the e-puck, start the Tiny Bootloader program on your computer. (Although you can also use a flash programmer such as the ICD2 to program the e-puck, it will take much longer and can't be done wirelessly.) Click on '''Browse''' and select the .hex file that you want to load. The .hex file is the compiled code from Microchip's C compiler. Under '''Comm''', use 115200 for the baud rate, and type in the outgoing COM port assigned to this e-puck (e.g. COM10, COM11, etc.). Turn on the e-puck, and click on the Write Flash button. The blue bar underneath the button should start counting down. Now, hit the blue reset button on the e-puck, before the blue bar reaches zero and times out. If the e-puck is successfully connected, an orange LED on the e-puck will turn on, and the bootloader will start to program the PIC on the e-puck.

===Troubleshooting===
* If Tiny Bootloader cannot connect to the COM port, make sure your e-puck is on, and that you've selected the correct COM port assigned to the e-puck (the ID of the e-puck is on a sticker on top of the bluetooth chip on the e-puck's PCB.
* If Tiny Bootloader can connect to the e-puck but cannot find the PIC, it may be that someone has overwritten the bootloader with another program. See the section below [[#Re-loading the Bootloader|Re-loading the Bootloader]] to see how to restore the bootloader with the ICD2 programmer and MPLAB.

====Re-loading the Bootloader====
The e-pucks require that a special bootloader program be loaded on it if you want to program the e-puck over a bluetooth radio.

You can download the .hex file you need at [http://www.e-puck.org http://www.e-puck.org]. On the website, go to Download>Software>Library and download the zip file. Extract the archive, and navigate to '''e-puck-lib\tool\bootloader\epuck_side'''. The file <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt> is the one we will use.

You will need Microchip's [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] and ICD2 to program in the bootloader on the PIC. After opening MPLAB, select to '''Programmer>Select Programmer>ICD2'''. Then, go to '''File>Import>''' and navigate to <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt>. Then, connect to the ICD and program the PIC.

=Starting the Vision System=
The vision system is needed to track the position of the robots and send out commands. You can get the compiled program here:[[Image:vision_system_localization_project.zip]][[Image:vision_localization.zip]]
# Connect an XBee radio with ID 0 to the computer. The ID must be 0 so that the robots can tell that the packet is from the computer and not another robot.
# Follow the directions on the [[Machine_Vision_Localization_System#Operation | Machine Vision Localization]] page to set up and calibrate the system.
# Make sure the robots are in the field of view of the vision system.
# Let the system run for a few seconds so that the robot's positions will be updated.
# Select the GUI window and hit 'c' to enter the command mode.
# Select the console window and enter the goal statistics that you want using the '''goal''' command. You can skip this step if you want to use the default [100 300 160000 40000 40000] goal statistics. Send the command 2 or three times in case one or more of the robots doesn't get the message.
# Use the '''wake''' command (<tt>wake 0</tt>) to start the robots.
# Exit the console by typing <tt>exit</tt>. The system should now be running.

Try moving the swarm to another configuration:
#press 'c' at the GUI window.
#enter the command <tt>goal 0 -100 -200 120000 0 120000 </tt>
#type <tt>exit</tt> and hit enter.

=Using the Real-Time Display=
See [[Swarm_Robot_Project_Documentation#Real-time_Display]]

=Using the Packet Parser with Timestamp=
See [[Swarm_Robot_Project_Documentation#Using_the_Data_Logger_with_Timestamp]]

Swarm Robot Quickstart Guide

2009-01-27T22:16:35Z

Hwang: /* Compiling the project */

__TOC__
This guide was written as a quickstart guide for the Swarm Robots Project, but contains general information about programming e-pucks.
=Checklist=
In order to run the system, you will need:
# e-puck robots, with XBee extension boards and [[Swarm_Robot_Project_Documentation#XBee_Radios|configured radios]].
# Bluetooth adapter on your computer, either internal or an external one such as the D-link DBT-120.
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Compiled .hex file found in e-puck code project]
# [http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm Tiny Bootloader]
# [[Machine_Vision_Localization_System|Compiled program for Machine Vision Localization System]].
# You may also want to use one or more of the [[#Analysis_Tools|Analysis Tools]] such as the real-time display.

==Items needed to edit the e-puck code==
If you want to edit the e-puck code, you will need the following:
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] (for editing code, not needed to run)
# Microchip [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en535363 C compiler for dsPICs] (for editing code, not needed to run)
# [http://hades.mech.northwestern.edu/wiki/index.php/Swarm_Project_E-puck_Code Code for e-pucks]

===Compiling the project===
To open the project, extract the directory and double-click on the '''<tt>.mcp</tt>''' file; this is the project file. Because the directory it is in is probably different from the original directory from the computer on which the code was written, you may need to remove and re-add the sources, library, and/or linker files to the project. The source files are in the '''source''' folder. The library and linker files are in the Microhip compiler's install directory(try searching for <tt>libp30F6014A-coff.a</tt> and <tt>p30f6014A.gld</tt>). Press f10 to compile the program. This should generate a .hex file, which is the binary file that you will load onto the e-Puck.

=Programming the e-pucks=
You will need to get the compiled .hex file for the e-puck, and then load it onto the PIC with Tiny Bootloader over the bluetooth radio. The compiled .hex file can be found here: [[Image:Swarm_epucks_code.zip]].
==Connecting to the e-puck==
To program the e-puck, you first need to connect to the e-puck. Go to the Control Panel, and open Bluetooth Devices, and go to '''Devices>Add...'''. Turn on the e-puck, check '''My device is set up and ready to be found''', then click next. When the computer has found the e-puck, select it (the ID of the epuck is a four-digit number found on a sticker on top of the bluetooth chip on the e-puck). When the prompt asks you for a passkey, enter the 4-digit ID number. The computer should then reserve a COM (serial) port to communicate with this particular e-puck. The computer will set up different COM ports for different e-pucks; this is normal. Go back to Bluetooth Devices in the Control Panel, and select the COM Ports tab, and see port is assigned '''Outgoing''' to the e-puck. This is the COM port you will use to program this particular e-puck when using Tiny Bootloader. '''If you're using a USB bluetooth dongle, if you unplug it and replug it into a different USB port, or use a different dongle, you may need to reconnect to the e-pucks.'''

[[Image:BT_COM_ports.png]]

==Programming the e-puck==
A bootloader is a type of program that is loaded onto a microcontroller which allows one to re-program the microcontroller in the field without having to use an special flash programmer (the programmer is still needed to load the bootloader onto the microcontroller in the first place). The Bootloader has two components: a programmer that runs on your computer, and a program that runs on the e-puck's PIC. When the PIC is turned on, bootloader will check to see if someone is attempting to re-program the PIC; if yes, the bootloader will overwrite its old program with the new program; if not, or if it times out while waiting for the new data stream, it will simply run the current program.

To program the e-puck, start the Tiny Bootloader program on your computer. (Although you can also use a flash programmer such as the ICD2 to program the e-puck, it will take much longer and can't be done wirelessly.) Click on '''Browse''' and select the .hex file that you want to load. The .hex file is the compiled code from Microchip's C compiler. Under '''Comm''', use 115200 for the baud rate, and type in the outgoing COM port assigned to this e-puck (e.g. COM10, COM11, etc.). Turn on the e-puck, and click on the Write Flash button. The blue bar underneath the button should start counting down. Now, hit the blue reset button on the e-puck, before the blue bar reaches zero and times out. If the e-puck is successfully connected, an orange LED on the e-puck will turn on, and the bootloader will start to program the PIC on the e-puck.

===Troubleshooting===
* If Tiny Bootloader cannot connect to the COM port, make sure your e-puck is on, and that you've selected the correct COM port assigned to the e-puck (the ID of the e-puck is on a sticker on top of the bluetooth chip on the e-puck's PCB.
* If Tiny Bootloader can connect to the e-puck but cannot find the PIC, it may be that someone has overwritten the bootloader with another program. See the section below [[#Re-loading the Bootloader|Re-loading the Bootloader]] to see how to restore the bootloader with the ICD2 programmer and MPLAB.

====Re-loading the Bootloader====
The e-pucks require that a special bootloader program be loaded on it if you want to program the e-puck over a bluetooth radio.

You can download the .hex file you need at [http://www.e-puck.org http://www.e-puck.org]. On the website, go to Download>Software>Library and download the zip file. Extract the archive, and navigate to '''e-puck-lib\tool\bootloader\epuck_side'''. The file <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt> is the one we will use.

You will need Microchip's [http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en019469&part=SW007002 MPLAB] and ICD2 to program in the bootloader on the PIC. After opening MPLAB, select to '''Programmer>Select Programmer>ICD2'''. Then, go to '''File>Import>''' and navigate to <tt>tinybld_ds6014A_7.37Mhz_115200uart1_8xPLL_with_LEDs.hex</tt>. Then, connect to the ICD and program the PIC.

=Starting the Vision System=
The vision system is needed to track the position of the robots and send out commands. You can get the compiled program here (no source code): [[Image:vision_localization.zip]]
# Connect an XBee radio with ID 0 to the computer. The ID must be 0 so that the robots can tell that the packet is from the computer and not another robot.
# Follow the directions on the [[Machine_Vision_Localization_System#Operation | Machine Vision Localization]] page to set up and calibrate the system.
# Make sure the robots are in the field of view of the vision system.
# Let the system run for a few seconds so that the robot's positions will be updated.
# Select the GUI window and hit 'c' to enter the command mode.
# Select the console window and enter the goal statistics that you want using the '''goal''' command. You can skip this step if you want to use the default [100 300 160000 40000 40000] goal statistics. Send the command 2 or three times in case one or more of the robots doesn't get the message.
# Use the '''wake''' command (<tt>wake 0</tt>) to start the robots.
# Exit the console by typing <tt>exit</tt>. The system should now be running.

Try moving the swarm to another configuration:
#press 'c' at the GUI window.
#enter the command <tt>goal 0 -100 -200 120000 0 120000 </tt>
#type <tt>exit</tt> and hit enter.

=Using the Real-Time Display=
See [[Swarm_Robot_Project_Documentation#Real-time_Display]]

=Using the Packet Parser with Timestamp=
See [[Swarm_Robot_Project_Documentation#Using_the_Data_Logger_with_Timestamp]]

Swarm Robot Project Documentation

2009-01-27T19:38:29Z

Hwang: /* Analysis Tools */

Machine Vision Localization System

2009-01-27T19:36:25Z

Hwang: /* Camera Calibration */

__TOC__
=Project Files=
*[[Image:vision_system_localization_project.zip]] (Project files with source code)

=Overview=
This is a machine vision system that tracks multiple targets and can send out the positions via the serial port. It was developed specifically for the [[Swarm_Robot_Project_Documentation|Swarm Robotics project]], but can be adapted for other uses. It is based upon the [[Indoor_Localization_System]], but has several enhancements and bug fixes. Refer to [[Indoor_Localization_System]] for a basic overview of the setup of the system and the workings of the patter identification algorithm.
==Major Enhancements/Changes==
* The system will now mark the targets with an overlay and display coordinate data onscreen.
* The serial output is now formatted for the XBee radio using the XBee's API mode with escape characters.
* The calibration routine has been improved, and only needs to be performed once.
* A command interface for sending out commands via the serial port has been added.
* The system will discard targets too close to the edge of the camera frame to prevent misidentification due to clipping.
* The origin of the world coordinate is now in the middle, not the lower left corner.
* The GUI displaying the camera frames is now full sized instead of a thumbnail. However, if your monitor isn't big enough, you can resize them.

==Major Bug Fixes==
* Two major memory leaks fixed.
* Calibration matricies are now calculated correctly.
* File handling bug that causes an off-by-one error in '''LoadTargetData()''' fixed.

==Target Patterns==
The target patterns and preprocessor can be downloaded at [[Indoor_Localization_System#Pre-processing_program_source_with_final_patterns:]].

=OpenCV Documentation=
[http://opencv.willowgarage.com/wiki/ OpenCV Wiki]

=Operation=
==Setting up the Cameras==
[[Image:camera_setup.png|300px|thumb|left]]
 

The cameras should be set up according to [[Indoor_Localization_System]] with one caveat: targets at the edge of the camera frame will now be discarded. This prevents misidentification of patterns if one or more dots in the pattern fall off the screen, but it also means that there must be enough overlap that when the target is in the dead-zone of one camera, it is picked up by another camera.

The height of the cameras will determine how small your patterns can be before becoming indistinguishable. Changing the height also changes the focus, so be sure to adjust the focus when the height is changed.

[[Image:machine_vision_single_frame.png|300px|thumb|left|Targets found in the margin are discarded.]]
 
[[Image:machine_vision_four_frames.png|300px|thumb|left|The frames must overlap; overlap by the width of one target to ensure that it will never be discarded by both cameras.]]
 
== How to Use The System ==
=== Camera Setup ===
The four cameras used were standard Logitech QuickCam Communicate Deluxes. For future use, the videoInput library used is very compatible and works with most capture devices. As measured, the viewing angle (from center) of the Logitech cameras was around 30 degrees (horizontal plane) and 25 degrees (vertical plane).

[[Image:visual_localization_viewing_angle.jpg|right|thumb|300px|Approximate Viewing Angle of Logitech Cameras]]

Before attaching the cameras, several considerations must be made.

'''1. Choose a desired ALL WHITE area to cover.''' '''***IMPORTANT: If you want to be able to cover an continuous region, the images as seen by the cameras must overlap to ensure a target is at least fully visible in one frame of a camera***''' Keep in mind that there is a trade-off between area, and resolution. In addition, the size of the patterns will have to be increased above the threshold of noise.

'''2. Ensure that the cameras are all facing the same direction. ''' As viewed from above, the "top" of the cameras should all be facing the same direction (N/S/E/W). For future use, if these directions must be variable, the image reflection and rotation parameters can be adjusted in software (though this has not been implemented).

'''3. Try to mount the cameras as "normal" as possible.''' Although the camera calibration should determine the correct pose information, keeping the lenses of the cameras as normal as possible will reduce the amount of noise at the edges of the images.
 

== Computer Setup ==
In the current implementation, this system has been developed for a Windows based computer (as restricted by the videoInput library). The system should run in Windows XP or Vista. To setup the computer to develop and run the software, the three required libraries must be installed.

1. Download and install the Logitech QuickCam Deluxe Webcam Drivers - http://www.logitech.com/index.cfm/435/3057&cl=us,en

2. Download and install Microsoft Visual Studio Express - http://www.microsoft.com/express/default.aspx

3. Download and install Microsoft Windows Platform SDK - http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en

4. Download and install Microsoft DirectX 9+ SDK - http://www.microsoft.com/downloads/details.aspx?FamilyId=572BE8A6-263A-4424-A7FE-69CFF1A5B180&displaylang=en

5. Download and install Intel OpenCV Library - http://sourceforge.net/projects/opencvlibrary/

6. Download and install the videoInput Library - http://muonics.net/school/spring05/videoInput/

7. Download the source code for the vision system here: [[Media: Vision_localization_system_project.zip]]

The project will probably not compile right after you open it. You will have to put the correct directories into the environment. In Visual C++, go to

Tools>Options>Project and Solutions>VC++ directories

and select '''Include files''' in the drop-down menu. Add '''(the directory paths on your computer may be different depending on your system, and the versions you installed.)''':
* C:\Program Files\OpenCV\otherlibs\highgui
* C:\Program Files\OpenCV\otherlibs\cvcam\include
* C:\Program Files\OpenCV\cvaux\include
* C:\Program Files\OpenCV\cxcore\include
* C:\Program Files\OpenCV\cv\include
* C:\Program Files\Microsoft SDKs\Windows\v6.1\Include

select '''Library files''' from the drop-down menu and add:
* C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib
* C:\Users\LIMS\Documents\Visual Studio 2005\Libraries\videoInput0.1991\videoInputSrcAndDemos\libs\DShow\lib
* C:\Users\LIMS\Documents\Visual Studio 2005\Libraries\videoInput0.1991\compiledLib\compiledByVS2005
* C:\Users\LIMS\Documents\Visual Studio 2005\Libraries\videoInput0.1991\videoInputSrcAndDemos\libs\videoInput

==Starting the Program==
# Compile and run the program.
# When you first run the program, it will open up a console window and ask you to enter a COM port number. This is the number of the serial port that will be used to send out data. Enter the number, and press Enter. (e.g. <tt>Enter COM number: 4<enter></tt>)
# The program should now connect to the cameras, and will open two new windows: one with numbered quadrants (the GUI window), and one displaying the view of one of the cameras. Use you mouse to click on the quadrant that corresponds to the camera view. Repeat until all four cameras have been matched to the quadrants.
# Make sure the GUI window is selected, and press Enter.
# Go back to the console window, and you should now see a message asking you if you want to recalibrate your cameras. Press '''<tt>y</tt>''' for yes and '''<tt>n</tt>''' for no, then press Enter. To recalibrate your cameras, see the calibration section.
# The GUI window should now show a thresholded image, and the console will display how many dots the camera sees. [[Indoor_Localization_System#Real_time_Adjustable_Parameters| Adjust the thresholding parameters]] (+ and - for black/white, z and x for area) until you are satisfied with the thresholded image.
# Make sure the GUI window is selected, then hit Enter.
# Remove any calibration patterns, and hit Enter. The program should now be running.
# When you turn on the robots, they will be in '''sleep''' mode. Use the '''wake''' command to start them.

==Camera Calibration==
The camera calibration routine used is explained in the document [[Media:Image_Formation_and Camera_Calibration.pdf | Image_Formation_and Camera_Calibration.pdf]] by Professor Ying Wu.

The calibration routine uses 9 equally-spaced points per camera to find a mapping from the image coordinates to the real-world coordinates. The field of view of the four cameras must overlap the center horizontal and vertical dots that form a '+' shape.

The center dot should be seen by all four cameras.

The size of the dots is not very important; the center of mass of each of the dots will be used.

[[Image:machine_vision_calibration.png|300px|thumb|left|Twenty-five points are used to calibrate the cameras. The field of view must overlap the dots that form a '+'.]]
 

To calibrate:
# Place the 25 equally spaced dots on the testbed. The dots should be well distributed throughout the testbed (don't bunch the dots all up in a small area).
# Start the program, and type in 'y' at the prompt that asks whether or not you wish to calibrate.
# Enter the horizontal spacing (parameter A in the diagram) and vertical spacing (parameter B in the diagram) when prompted. These numbers are recorded in the file <tt>calibration_dot_spacing.txt</tt>.
# The GUI window will then display a thresholded image and the console will display the number of dots seen by each camera. Adjust the thresholding values until each camera sees only the nine dots being used to calibrate the camera.
# Select the GUI window and hit Enter.
# Remove the dots.
# Select the GUI window and hit Enter.

The program should now be running. Your calibration information will be recorded in <tt>Quadrant0.txt, Quadrant1.txt, Quadrant2.txt, Quadrant3.txt,</tt> and <tt>calibration_dot_spacing.txt</tt>. If you choose not to recalibrate your cameras next time, the data in these files will be used to generate the calibration matrices.

When calibrating, the dots should be raised to the same height as the patterns on the robots. It is possible to calibrate one camera at a time using only 9 dots by placing the dots under one camera at a time and running the calibration routine four times, making a copy of the <tt>Quadrant_.txt</tt> file generated by the calibration routine for that camera (the other three files will be garbage) each time so that it will not be overwritten. You can then copy the four good files back into the directory.

==Pausing==
Hit 'p' to pause the program, and hit 'p' again to resume.

==Using the Command Console==
To enter the command mode, hit 'c'. When in the command mode, the main loop is not running; the command mode must be exited to resume. Type 'exit' to exit the command mode and resume the main loop.

'''Note: There is no guarantee that all of the robots will receive the command, due to packet loss. It is advisable to send the command out multiple times to make sure the robots all receive it. You can use the arrow keys to find previously sent messages.'''

Enter commands in the following syntax:

<tt><command name> <target ID> <parameter 1> <parameter 2> ... <parameter N></tt>

'''To broadcast the message, use ID 0.'''

You can also enter multiple commands at a time:

<tt>sleep 1 sleep 2 wake 4 goto 0 100 -100 deadb 0 150</tt>
===Commands===
{| class="wikitable" border="3"
|+'''Commands Table'''
|-
! Command !! Description !! Parameters !! Example
|-
| sleep || The robot will stop moving and stop sending data. || <tt>sleep <ID></tt> || <tt> sleep 0 </tt>
|-
| wake || The robot will wake from sleep and resume moving and sending data || <tt>wake <ID></tt> || <tt> wake 0 </tt>
|-
| goal || Change the swarm's goal state. || <tt>goal <ID> <Ix> <Iy> <Ixx> <Ixy> <Iyy> </tt> || <tt> goal 0 100 300 160000 40000 40000 </tt>
|-
| goto || Similar to <tt>goal</tt>, but only changes <tt><Ix></tt> and <tt><Iy></tt>. || <tt>goto <ID> <Ix> <Iy> </tt> || <tt> goto 0 100 300</tt>
|-
| deadb || Change the robot motor deadband. The motors will only move for speeds (wheel ticks per second) faster than this. This removes some jittering at low speeds. || <tt>deadb <ID> <velocity> </tt> || <tt> deadb 0 150</tt>
|-
| egain || Change the estimator gains. || <tt>egain <ID> <KP> <KI> <Gamma> </tt> || <tt> egain 0 0.7 0.1 0.05</tt>
|-
| cgain || Change the motion controller gains. || <tt>cgain <ID> <KIx> <KIy> <KIxx> <KIxy> <KIyy> </tt> || <tt> cgain 0 2 2 0.001 0.001 0.001</tt>
|-
| commr || Change the communication radius distance. The agent will discard any packets from other agents further away than this distance. || <tt>commr <ID> <distance> </tt> || <tt> commr 0 1500</tt>
|-
| speed || Change the maximum allowed speed for the robot. || <tt>speed <ID> <speed> </tt> || <tt> speed 0 300</tt>
|-
| safed || Change the obstacle avoidance threshold. || <tt>speed <ID> <distance> </tt> || <tt> safed 0 200</tt>
|-
|}

==Exiting the Program==
Press ESC to quit the program.