Mech - User contributions [en]

Setup, Use, and Modeling of Harmonic Drive Motors with Junus Amps

2013-05-16T16:29:09Z

NealEhardt: /* Motor Modeling */

= Setting up the Junus Amplifier =

[[Image:power_supply_diagram.png|thumb|Power Supply Diagram|right]]
The first thing you need to run the amplifier is to find a DC power source that outputs 20-90V with a maximum current greater than what you expect your motor(s) to draw. This should be connected to the amplifier according to the following diagram, where the capacitors and diodes are rated for the voltages/currents you are expecting to see.
 

Next, use the USB to RS-232 cable to connect the amp to your PC. If this doesn't work you will need to find and install the driver for the HL-340 USB to serial converter (there is a copy of the driver in the folder Philip's Files\usb-serial-driver.zip on the desktop of the PC used for the QNX manipulation project). You will also need to download and install [http://www.copleycontrols.com/Motion/Downloads/index.html CME2] (Copley Motion Explorer); note that Copley's documentation for the amplifier and software can also be downloaded from the same page.

 
[[Image:copley_basic_setup.png|thumb|Basic Setup Menu|right]]
Open the program and add the COM port used by the USB to serial cable to the list (the list can be changed later in the Tools -> Communication Wizard menu). Next go to Amplifier -> Basic Setup. Here you select from the different operational modes and input types.
 

== Operating Modes ==
* Current - This is the most commonly used mode. Here, the amplifier will create an output current proportional to some input signal to drive the attached actuator. In this mode there is only one control loop running within the amplifier making it the preferred choice (the more control that can be done outside the amp, the less of a black box it is).
* Velocity - This mode takes the current control mode and adds another feedback loop around the current control loop so that the velocity of the motor is proportional to the input signal. For the Junus amps, the motor speed is estimated from the back emf of the motor during use, making it less reliable than the current control mode.

== Command Sources ==
 
[[Image:junus_amp_pin_diagram.png|thumb|Junus Amp Input Pin Diagram|right]]
The pin diagram for the Junus amp is found to the right.
* Analog Command - In this mode, an analog input is connected to pins 2 and 9, with the analog reference voltage going to pin 9 and the signal going to pin 2. The voltage range for the input is +/- 10V with the output being proportional to the voltage, i.e. 0V is 0A (or 0rpm) output, +10V is maximum positive current output, and -10V is maximum negative current output.
* PWM Command - In this mode the output is related to the duty cycle of the PWM signal in one of two ways. To switch between these modes, click on the PWM command button in the block diagram.
** 50% mode - This mode uses a single input pin (pin 3). Here a 50% duty cycle is the zero point (0A or 0rpm) with 0% being fully negative and 100% being fully positive.
** 100% mode - In addition to the PWM input pin there is an extra input pin (pin 4) to control the sign (or direction) of the output. Here, a 0% duty cycle is the zero point, 100% duty cycle with the direction pin LO is fully negative and 100% duty cycle with the direction pin HI is fully positive.
 

Now click on the Motor button in the block diagram. Here you can input all the necessary parameters about your motor from the data sheet, or that you experimentally found. Now you are ready to look at the control loop. There is a PI controller with tunable parameters used to control the output current. While you are welcome to play around with the parameters on your own, I would suggest that you click on the I Loop button and select Auto Tune, at least to get a starting point for the parameters. It will give you several options based on different levels of aggressiveness of the controller.

Click on Input/Output. Here you can set up the different input and output pins. I recommend using IN1 as Amp Enable-HI (or LO) Enables With Clear Faults (pin 13). This ensures that the motor can only spin when you give it a command to turn on. Choose HI if your digital outputs default to LO, or vice versa, as it can vary depending on the presence of pull-up resistors, etc. You now have your amp configured and you are ready to start controlling your motor.

There are also a couple of other utilities built into the CME2 software. The first is the Control Panel (second button from the left in the top menu). This allows you to software enable/disable the amplifier as well as monitor various inputs/outputs of the motor during use. The other is the Scope (third button from the left in the top menu). This lets you apply various functions to drive the motor and monitor inputs/outputs over time. This is useful for making sure your control parameters are tuned the way you like them.

= Using the Motor =

If you are using analog command mode, a simple test to make sure your setup is working correctly is to connect the enable pin to +5V (or GND, depending on how it was configured) and use a potentiometer to control the input voltage and make sure the motor spins as you would expect it to. As a reminder, 0V is 0 output, negative voltage will move it in one direction and positive voltage in the other.

If you are using PWM command mode, a more involved test would be to do the activity found [[ME 333 Lab 4 | here]]. For our system, the plant would be the entire amp/motor package and feedback loop in the diagram at the top is designed to control the position of the motor.

= Motor Modeling =

For our purposes, we have chosen to model the motor using the following equation, where <math>\tau</math> is the output torque, <math>k_m</math> is the motor constant, <math>i</math> is the command current, <math>\mu_d</math> is the dynamic friction coefficient, <math>\mu_s</math> is the static friction, <math>\omega</math> is the speed of the motor, and the <math>sgn</math> function returns the sign of its argument.

<math> \tau = k_m i - \mu_d \omega - \mu_s sgn(\omega) \,</math>

This can be easily solved to find the necessary command current (and thus the analog or PWM input) needed to follow a reference trajectory, which would be the feedforward model of our system.

== Setup ==

To determine the values of the parameters in the above equation, you should run a series of tests at various input levels to make sure the parameters are constant at various speeds and accelerations of the motor. To set up the experiment you will need a mount for the motor (a table-mount vice works well), an object of known inertia (ex. momentum wheel), and you will need to hook up the encoder on the motor to a device that can read it in (ex. decoding chip connected to a PIC).

== Experiment ==

 
[[Image:motor_model_wiring.png|200px|Wiring diagram for the motor modeling setup|right]]
For each run of the experiment, the motor is driven by three periods of a square wave current at a specified amplitude. Multiple periods are used to allow transient behavior to die down and for filtering purposes, described in the following section. During each run the position from the encoder is recorded and post-processing is used to find the velocity and acceleration associated with the trajectory.

Code used to drive the motor during the experiment can be downloaded [[Media:motor_model_PIC_code.zip|here]]. This code is meant to be run on the [Introduction to the PIC32|PIC32 board]. The basic wiring diagram is to the right and the datasheet for the LS7083 decoder can be found here [http://pdf1.alldatasheet.com/datasheet-pdf/view/71312/LSI/LS7083.html] and includes all the wiring diagrams necessary.

To actually run the experiment, use the MATLAB code [[Media:motor_model_analysis_code.zip|here]]. The function dataCollection takes in the amplitude of your square wave current and outputs this to the amp. It then collects the trajectory data and saves it to a .mat file (see file for details on directory and file name format). Note that the COM port, Imax (maximum current set on the amp), and other variables must be changed in both the MATLAB code and the amp or PIC.
 

== Filtering ==

 
[[Image:filtering_example.png|200px|An example of filtering data|right]]
To find the velocity and acceleration of the motor during the experiment, the raw data from the encoder must be smoothed otherwise there are large spikes in the calculated derivatives due to signal noise, etc. To smooth the data, a moving average is used (this is why we collected extra periods of data, so we can still apply the moving average to the end points). The idea of a moving average is the filtered value at a specific time is the average of the unfiltered value and the nearest N values in each direction. Choosing a low N leads to less smoothing but retains more of the original data. I found that an N of 5 was good for my data set, but this will be different for each application depending on the amount of noise, etc. The number of points to use in the filter is the second (and optional) argument to the MATLAB file fitParameters. In this function, the raw data is first smoothed using the moving average, then finite differences are used to calculate the velocity. This is then smoothed using the same moving average and finite differences are used again to find the acceleration.
 

== Fitting Parameters ==

 
[[Image:model_example.png|200px|An example of motor model data|right]]
Now that you have the acceleration, you can easily find the torque because you know the inertia of the object being rotated. Going back to the model, you now have the torque and velocity so you can solve for the three unknowns. You can also choose to model the motor as having a different set of parameters for positive and negative torques, something I found to work better than a single set of parameters.

In the figure to the right, an example of a motor model is shown, with trials run at 50 mA intervals from 150 to 400 mA. The filtered data is plotted as the dots and the ideal model based on the calculated parameters are the solid lines, this type of plot can be generated from the function batchProcess. In this plot, the effect of filtering is evident in the rounded edges near the transition points (crossing zero velocity and zero acceleration lines). You can also see the motor is reaching its maximum speed at 200 mA.

Swarm Robot Project Simulator

2009-12-01T04:22:17Z

NealEhardt: /* Versions */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Versions=
There are now two versions of the simulator that implement different algorithms. They both use the same control structure, which this article outlines in context of the formation control algorithm.

==Formation control==
File: [[Image:Swarm_Robot_Project_Simulator.zip]]

Here the robots orient themselves so that their moments (quantifiers of the group's shape and position) match a predefined set of goal moments.

The swarm will start centered around a random point and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Environment sensing==
File: [[Image:Swarm_Robot_Project_Simulator_environment.zip]]

Here the robots are placed in an environment with up to 3 variables that are functions of location. The robots collaboratively model these variables and relocate themselves to get optimal sensor readings.

The swarm starts clustered at a random location in an environment with randomly chosen parameters. The three environment variables are displayed on top of each other as red, green, and blue. Click on an agent to open a plot of its error (a black field indicates perfect estimate of all colors). The environment function is defined in ''basefunction.m'' and it can be changed to anything.

For this application, the agents' states have three extra data fields:
* '''bots'''
** '''state'''
*** '''Y''' information matrix
*** '''Tau''' information vector
*** '''sensorR''' sensor covariance

=Getting started=
To run the simulator:
# Download one of the zip files above.
# Extract the ''Simulator'' folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==Code organization==
Each M-file is a MATLAB function. The central one is ''simulator.m''. At the top of ''simulator.m'', you will find some constants (denoted by all-caps) that make it easy to change the performance and rendering of the simulation without having to read into the code. See the inline comments for details.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes from the flowchart to the right represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

Note: the present algorithm does not work very well.

=Environment=
The environment is a set of abstractions that encapsulate the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a struct, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the agent knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet ''i'' of bot ''i'' is that agent's own estimate and always has an age of 0.)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity chosen by Controller
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between last update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/ The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

[[Category:SwarmRobotProject]]

Swarm Robot Project Documentation

2009-11-18T20:53:15Z

NealEhardt: /* Simulator */

__TOC__
==Overview==
Nullam tincidunt, tellus sit amet elementum imperdiet, nunc arcu imperdiet nisl, vitae hendrerit erat nulla eu erat. Vivamus suscipit ante quis leo volutpat mollis. Proin placerat dui id arcu fringilla aliquam. In nec felis a ligula molestie ultrices. Curabitur dapibus vulputate nulla fermentum sollicitudin. Mauris id dui neque, et ultricies ante. Maecenas ac arcu at mauris posuere ultricies at sit amet magna. Etiam eu eros nunc, non hendrerit dui. Morbi blandit dui sed orci euismod eget dignissim purus fermentum. Curabitur nunc arcu, auctor et semper eu, aliquet a odio. Nam ut leo at sapien dictum luctus eu non nibh.

To quickly get a grasp of how to run the '''Swarm Consensus Estimation Project''', refer to the '''[[Swarm_E-puck_Quickstart_Guide|Swarm e-puck Quickstart Guide]]'''. This guide provides instruction on setting up the computer systems, what programs to run, and how to configure the e-pucks. For more detailed information about each step, such as program configuration, etc, please read through this article.

==The e-puck==
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 small size of the e-puck made it ideal for the project, and the stepper motor driven wheels offered consistency and accuracy, both of which are highly desirable features for experiments requiring 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/], and additional documentation by going to '''Download>Documentation'''.

===[[Swarm_Project_E-puck_Code|e-puck code]]===
The Swarm Consensus Estimation Project E-puck code can be downloaded here: '''[[Media: Swarm_epucks_code.zip|Swarm Consensus Project e-puck Code]]'''

Documentation of the code can be found at '''[[Swarm_Project_E-puck_Code|Swarm Consensus Project e-puck Code Documentation]]'''.

The e-puck code 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 e-pucks will start out in 'sleep' mode, meaning they do not send out packets, nor do they move. Use the [[Machine_Vision_Localization_System#Commands|'wake' command]] in the vision system command window to wake the e-pucks.

==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. Using API 2 packets is important in order to ensure that corrupted or incomplete packets are dropped. For more information about the API modes (1 and 2), and their uses, refer to [http://www.digi.com/support/kbase/kbaseresultdetl.jsp?kb=184 this] and [http://www.digi.com/support/kbase/kbaseresultdetl.jsp?id=2199 this] as well as the XBee [http://www.digi.com/products/wireless/point-multipoint/xbee-series1-moduledocs.jsp manual and datasheets].

===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 individual number is a 32-bit floating point value, or 4 bytes each, which means that the data frame is 60 bytes long (15 x 4 = 60), although it could be longer if escape characters are needed (see ''API Operation'' in the XBee Manual).

Additional values may be added to the packet data frame. For example, the e-pucks currently are fitted with a color sensor board, allowing the e-puck to detect the color of the environment it is in. Tracking and logging these values (red, green, blue) is important, and thus three additional values are added to the data frame. Consequently in the packet handling (XBeePacket) code, the "additional_num" value must be changed from 5 to 8 to accommodate three additional values. This change must be made across all the packet handling code, on both the computers and e-pucks, as an e-puck will not be able to read code with 15 values if its own code is changed to send/receive 18 value packets. The resulting packet data frame would contain the same values 1 - 15 as above, but also 16, 17 and 18, which would represent the R, G, and B values from the color sensor.

==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.zip|Xbee Interface Extension Board Version 2]]. 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)

==Machine Vision Localization System==
A vision system was developed for robot localization, similar to GPS for each individual robot. The system uses cameras mounted overhead and pattern recognition algorithms to track the position and orientation of various targets (robots) 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==
A MATLAB simulation of the swarm can be found here: [[Swarm Robot Project Simulator]].

Here's early version implementing the formation control algorithm: [[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. To align the plotting coordinates with the real-world coordinates, we will use nine equally spaced points arranged in a rectangle centered at the origin for reference points (for example, we can use the center 9 of the 25 dots used to calibrate the camera. Therefore, we need at least a frame where the dots can be seen.

This script assumes that your camera is mounted above the workspace, pointed directly down. It also assumes that your camera has no distortions, and that the x and y axes are perfectly horizontal and vertical, respectively.

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==

===Aligning the Axes===
To generate the video, you first need to download the Matlab .m files: [[Image:swarm_plotting_files.zip]].

Extract the files, and take the '''Frames''' folder holding the movie frames and '''main_log.m''' generated by the data logger, and put them in the extracted folder which also holds VIDEO_OVERLAY.m

We must now align the plotting axes with the real world axes in the video, so that the position and SCALE will be correct when we overly the figures. To do this, we will use nine equally spaced points arranged in a rectangle centered at the origin. The alignment parameters are saved, so you only need to do this once if you don't move the camera. If need be, you can make a short video clip with marked points on the testbed just for alignment.

To perform the alignment,
#Make sure RES is set to the width and height of the resolution of the frames, in pixels (e.g. [width height]).
#Go to DOT_X and DOT_Y and set these to the x-axis and y-axis spacing between each of the nine dots in the real world.
#Set TEST_OVERLAY_FITTING = 1 and GEN_MOV = 0 and run the script. This will plot a square and nine '+' points in on top of the first frame of the video. Make sure the square is a true square, and not distorted.
#Adjust X_OFFSET and Y_OFFSET until the center '+' is lined up with the center dot (the origin of the real world coordinate system).
#Adjust SCALE until the other 8 dots are well matched up. SCALE will scale the axis, so increasing SCALE will increase the range of the axis, thus decreasing the unit distance.
#The overlay axes should how match the real world axes in the video.
#Reset TEST_OVERLAY_FITTING = 0.

===Setting Configurations===
If you run the '''VIDEO_OVERLAY.m''' script with 'GEN_MOV=0', you can preview what the video will look like, but the video will not be saved.

To generate the video, you need to enter the settings that you want.
*VIDEO_TIME=''TIME_IN_SECONDS'': (default = 75) This is the desired video duration in seconds. You must have enough data and video frames to generate the video of this duration.
*FPS=''FRAMES_PER_SECOND'' (default = 30) This is the frames per second of the video footage.
*GOAL =''GOAL STATISTICS'' (default = [100 300 160000 40000 40000]) This is an array that contains the goal's initial first moments and second central moments ([x y xx xy yy]). If you change the goal from the command console and the data logger recorded it, these values will be overwritten.
*COMMR =''COMMUNICATION_RADIUS'' (default = Inf) This is the default communication radius in millimeters. If you change the radius from the command console and the data logger recorded it, this value will be overwritten.

===Draw Options===
*DRAW_COMM_LINKS: =1 to draw communication links, =0 otherwise.
*DRAW_SWARM_ELLIPSE: =1 to draw actual ellipse representing swarm, =0 otherwise.
*DRAW_GOAL_ELLIPSE: =1 to draw the goal ellipse, =0 otherwise.
*DRAW_INDIVIDUAL_ESTIMATES: =1 to draw the individual estimates of the swarm of each robot, =0 otherwise.
*DRAW_ROBOT_MARKER_DOT: =1 to draw colored dots on top of the robots, = 0 otherwise.
*COMM_LINE_THICKNESS: the thickness of the lines if communication links are drawn.
*DOT_MARKER_SIZE: the size of dot marker if the dots are drawn.

===Generate Movie File===
GEN_MOV: =1 to generate and save the movie (could take a long time), =0 for preview only (much faster, but video won't be saved).

===Repairing Damaged Videos===
Sometimes, the video generated by MATLAB will be damaged. You can try to repair the file by opening it with VirtualDub, selecting '''Video>Direct Steam Copy''', and then '''File>Save as AVI'''.
===Compressing the Video===
There are many ways to compress the video, including using VirtualDub or Quicktime. To compress the video with Quicktime, open the video and select '''File>Export'''.

To use VirtualDub, select '''Video>Full Processing Mode''', go to '''Video>Compression''' and select the compression you want to use (you must have the codecs installed on your system), and the go to '''File>Save as AVI'''.

[[Category:SwarmRobotProject]]

File:Swarm Robot Project Simulator environment.zip

2009-11-17T19:55:08Z

NealEhardt:

Swarm Robot Project Simulator

2009-11-17T19:52:22Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Versions=
There are now two versions of the simulator that implement different algorithms: formation control and environment sensing. They both use the same control structure, which this article describes from the perspective of the formation control algorithm.

==Formation control==
File: [[Image:Swarm_Robot_Project_Simulator.zip]]

The swarm will start centered around a random point and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Environment sensing==
File: [[Image:Swarm_Robot_Project_Simulator_environment.zip]]

The swarm starts clustered at a random location in an environment with randomly chosen parameters. The agents monitor three variables, displayed as red, green, and blue. Click on an agent to open a plot of its error (a black field indicates perfect estimate of all colors). The environment function is defined in ''basefunction.m'' and it can be changed to anything.

=Getting started=
To run the simulator:
# Download one of the zip files above.
# Extract the ''Simulator'' folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==Code organization==
Each M-file is a MATLAB function. The central one is ''simulator.m''. At the top of ''simulator.m'', you will find some constants (denoted by all-caps) that make it easy to change the performance and rendering of the simulation without having to read into the code. See the inline comments for details.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes from the flowchart to the right represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

Note: the present algorithm does not work very well.

=Environment=
The environment is a set of abstractions that encapsulate the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a struct, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the agent knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet ''i'' of bot ''i'' is that agent's own estimate and always has an age of 0.)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity chosen by Controller
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between last update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/ The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

[[Category:SwarmRobotProject]]

Swarm Robot Project Simulator

2009-08-27T20:12:59Z

NealEhardt: /* Packet model */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the ''Simulator'' folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Organization==
Each M-file is a MATLAB function. The central one is ''simulator.m''. At the top of ''simulator.m'', you will find some constants (denoted by all-caps) that give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes from the flowchart to the right represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

Note: the present algorithm does not work very well.

=Environment=
The environment is a set of abstractions that encapsulate the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a struct, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the agent knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet ''i'' of bot ''i'' is that agent's own estimate and always has an age of 0.)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity chosen by Controller
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between last update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/ The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

[[Category:SwarmRobotProject]]

Swarm Robot Project Simulator

2009-05-28T19:30:12Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the ''Simulator'' folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Organization==
Each M-file is a MATLAB function. The central one is ''simulator.m''. At the top of ''simulator.m'', you will find some constants (denoted by all-caps) that give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes from the flowchart to the right represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

Note: the present algorithm does not work very well.

=Environment=
The environment is a set of abstractions that encapsulate the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a struct, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the agent knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet ''i'' of bot ''i'' is that agent's own estimate and always has an age of 0.)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity chosen by Controller
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between last update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-28T04:37:48Z

NealEhardt: /* Data model */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the Simulator folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

==Files==
Each file is a MATLAB function. The central one is ''simulator.m''. See Control Structure for details about the other ones.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

The present algorithm does not work very well.

=Environment=
The environment encapsulates the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a struct, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the agent knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet ''i'' of bot ''i'' is that agent's own estimate and always has an age of 0.)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity chosen by Controller
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between last update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-27T15:42:28Z

NealEhardt: /* Time model */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the Simulator folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

==Files==
Each file is a MATLAB function. The central one is ''simulator.m''. See Control Structure for details about the other ones.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

The present algorithm does not work very well.

=Environment=
The environment encapsulates the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events, such as updating robot calculations or rendering. Their size (relative to other time-based units) is defined by the constant ''dT''.

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-25T19:14:38Z

NealEhardt: /* Consensus Input */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the Simulator folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

==Files==
Each file is a MATLAB function. The central one is ''simulator.m''. See Control Structure for details about the other ones.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle. In the formation control implementation, this step causes the estimates to follow the agents instead of converging to the starting location.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

The present algorithm does not work very well.

=Environment=
The environment encapsulates the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-25T19:02:28Z

NealEhardt: /* Getting started */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the zip file: [[Image:Swarm_Robot_Project_Simulator.zip]]
# Extract the Simulator folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

==Files==
Each file is a MATLAB function. The central one is ''simulator.m''. See Control Structure for details about the other ones.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

The present algorithm does not work very well.

=Environment=
The environment encapsulates the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

File:Swarm Robot Project Simulator.zip

2009-05-25T19:00:25Z

NealEhardt:

File:Swarm simulator control structure.png

2009-05-25T18:58:02Z

NealEhardt:

Swarm Robot Project Simulator

2009-05-25T18:47:38Z

NealEhardt: /* Control structure */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a modular control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# [[Image:Swarm_Robot_Project_Simulator.zip|Download the zip file]] and extract the Simulator folder.
# Open ''simulator.m'' and press Run.
# When prompted, select "Change Directory".

==What you're seeing==
This version implements the formation control algorithm. The swarm will start centered around a random location and then converge on the goal moments (shown as the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code. See the inline comments for details.

==Files==
Each file is a MATLAB function. The central one is ''simulator.m''. See Control Structure for details about the other ones.

=Control structure=
[[Image:swarm_simulator_control_structure.png|300px|right|thumb|Control structure flowchart]]
The control structure represents the decentralized code that runs on the individual e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.

==Blue boxes==
The blue boxes represent functions that are defined in their own files. They are the building blocks of the consensus-based swarm model.

===Plant===
The interface between the agent and the environment. For the formation control implementation, this models an e-puck following a velocity vector.

===Sensors===
Consolidates information from the environment into a form readable by Consensus Input and the Controller.

===Consensus Estimator===
A discrete-time PI estimator that uses packet structs for its input and output.

===Consensus Input===
Injects the agent's own information into the estimator-communication cycle.

===Controller===
Uses the agent's sensory and consensus information to select a set of controls, sent to the plant.
 

==Collision avoidance==
The velocity output from the Controller is put through a collision avoidance algorithm. It is not shown in the flowchart because the algorithm has access to the positions of all the agents (information not known to any single agent).

The present algorithm does not work very well.

=Environment=
The environment encapsulates the control structure, simulating passage of time, motion of the agents, and lossy wireless communication.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It updates the plant every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by setting the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because the last communicated packet is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-25T06:51:40Z

NealEhardt: /* Getting started */

Swarm Robot Project Simulator

2009-05-25T06:37:31Z

NealEhardt:

Swarm Robot Project Simulator

2009-05-25T03:06:34Z

NealEhardt:

Swarm Robot Project Simulator

2009-05-25T03:04:26Z

NealEhardt: /* Recording a movie */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the m-file
# Open it and press Run.
# If prompted, select "Change Directory".

This version implements the formation control algorithm. When run, the swarm will start centered around a random location and then converge in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

=Constants=
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

=Control structure=
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.
 

=Environment=
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by turning the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because it is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, simply set MOVIE_FRAME_COUNT to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T21:23:02Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
To run the simulator:
# Download the m-file
# Open it and press Run.
# If prompted, select "Change Directory".

This version implements the formation control algorithm. When run, the swarm will start centered around a random location and then converge in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

=Constants=
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

=Control structure=
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model.
 

=Environment=
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields:
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle''' rotational orientation
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age''' timesteps since received
*** '''v''' PI decision variable
*** '''w''' PI estimator state
** '''u''' velocity
** '''lastUpdate''' timestep of last update
** '''waitTime''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by turning the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because it is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length, in frames. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T18:58:25Z

NealEhardt: /* Control structure */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

=Constants=
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

=Control structure=
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.
 

=Environment=
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by turning the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because it is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T16:44:49Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

=Getting started=
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

=Constants=
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

=Control structure=
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.

=Environment=
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

==Packet model==
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by turning the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because it is older than PACKET_AGE_LIMIT.

=Recording a movie=
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T16:44:13Z

NealEhardt: /* Packet model */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

==Getting started==
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

==Control structure==
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.

==Environment==
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

===Time model===
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

===Data model===
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

===Packet model===
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance. Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

===Visualizing packet loss===
Packet loss can be easily visualized by turning the constant DRAW_CONNECTIONS to true.

Between two agents...
* '''a black line''' means at least one agent has a fresh packet from the other.
* '''a red line''' means neither has fresh data, but at least one is using stale data.
* '''no line''' means neither agent is using data from the other because it is older than PACKET_AGE_LIMIT.

==Recording a movie==
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T16:30:13Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

==Getting started==
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for details.

==Control structure==
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.

==Environment==
The environment encapsulates the control structure, simulating wireless communications, passage of time, and the motion of the robots.

===Time model===
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

===Data model===
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

===Packet model===
Consensus information is transferred between the e-pucks using wireless communications. The simulator transfers packets between robots on an asynchronous basis and includes the possibility of packet loss as a function of distance.

Each robot's ''packets'' vector contains the most recently received packet from each of its neighbors. A robot will transmit its own consensus information just before its control structure is executed.

Packet loss is modeled by a cumulative Rice function, as advised by [http://www.springerlink.com/content/u34264k58822l872/|The problem of Wi-Fi radio-fading simulation: Solution and applications]. As distance between agents increases, the probability of receiving a packet decreases.

==Recording a movie==
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T15:58:15Z

NealEhardt: /* Control structure */

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

==Getting started==
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for more details.

==Control structure==
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

==Recording a movie==
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs at full quality because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T15:55:45Z

NealEhardt:

The simulator is a part of the [[Swarm Robot Project]] that attempts to model the robots using MATLAB. It is built around a generic control structure so that it can be easily adapted to run other algorithms. Features include: asynchronous update cycles, a packet model, lossy communication, and flexible rendering options.

==Getting started==
The simulator is contained in a single executable M-file. This version implements the formation control algorithm. When it is run, the swarm will start centered around a random location and then move in on the goal moments (the stationary green ellipse). The user may click a location on the grid to restart the simulation with the robots centered around that point.

==Constants==
The constants at the top of the M-file (denoted by all-caps) give the user a great deal of control over the performance and rendering of the simulation without having to understand the code.

See the inline comments for more details.

==Control structure==
[[Image:swarm_simlulator_control_structure.png|300px|right|thumb|Control structure flow chart. Blue boxes represent functions that can be found in the code.]]
The control structure is the logic portion of the code, representing code that might actually be run on the e-pucks. It is written modularly and without extraneous dependencies so it can be readily adapted to other algorithms.

The whole control structure is called from the ''updateBotComputations''. Information about neighbors flows to and from the consensus estimator via the packet model. Currently, no information from the environment is used by ''sensors''.

==Time model==
The simulation advances in ''timesteps''; equally spaced spans of time. Timesteps are the unit used in specifying the distance between discrete events (ie. updating robot calculations or rendering).

The main loop runs once per timestep. It moves the robots along their chosen velocity vectors every timestep and makes calls to time-dependent update functions as needed.

==Data model==
Since all state data in the simulation can be associated with a robot, the only stored variable is a vector of N robots called ''bots''. Each bot is individually represented as a structure, with the following fields (''and initial value''):
* '''bots''' vector of N robots
** '''state''' information the robot knows about itself
*** '''p ([''rand''; ''rand''])''' position (arranged randomly inside a square of side length SIDE, centered about a specified point)
*** '''angle (''rand'')''' direction facing
** '''packets''' vector of N received packets (packet i of bot i is that robot's own estimate and does not age like the rest)
*** '''age (PACKET_AGE_LIMIT+1)''' timesteps since received
*** '''v ([0; 0; 0; 0; 0])''' moments (packet i of bot i has v initialized to [p(1), p(2), 0, 0, 0])
*** '''w ([0; 0; 0; 0; 0])''' I have no idea
** '''u ([0; 0])''' velocity
** '''lastUpdate (0)''' timestep of last update
** '''waitTime (''rand'')''' timesteps between previous update and next update

==Recording a movie==
To record a run of the simulation, simply set MOVIE_FRAMES to the desired movie length. The movie will be saved as "movie.avi" in the same directory as the simulator M-file.

Movies are recorded as uncompressed AVIs at full quality because MATLAB does a poor job of compression. See [[Swarm Robot Project Documentation#Making Videos with Overlays]].

Swarm Robot Project Simulator

2009-05-07T15:38:14Z

NealEhardt: /* Control structure */

File:Swarm simlulator control structure.png

2009-05-07T15:26:43Z

NealEhardt:

Swarm Robot Project Simulator

2009-05-07T15:26:20Z

NealEhardt: /* Control structure */

Swarm Robot Project Simulator

2009-05-07T15:24:38Z

NealEhardt:

Template:PIC

2009-04-23T20:12:30Z

NealEhardt:

{| border="2" cellpadding="3" width="100%"
!colspan="2" style="background:#efefFf;" | [[PIC Microcontroller]]
|-
| '''[[PIC MCUs: Capabilities of PIC18F4520|PIC18F4520]]''' || width="100%" | [[Digital inputs & outputs|Digital I/O]] • [[PIC18F4520: Analog Inputs|Analog Input]] • [[PIC18F4520: PWM Motor Control|PWM Motor Control]] • [[PIC MCUs: 4520 Board|4250 Board]] • [[Sample code for most PIC18F4520 operations|Sample code]]
|-
|'''General Communication''' || [[PIC RS232|RS232 (Serial)]] • [[SPI - Serial Peripheral Interface - on the PIC|SPI]]
|-
|'''Inter-PIC Communication''' || [[I2C communication between PICs|I2C]] • [[IR communication between PICs|IR]] • [[SPI communication between PICs|SPI]] • [[XBee radio communication between PICs|XBee]]
|-
|'''Coding''' || [[PIC Microcontrollers with CCS Compiler|CCS Compiler]] • [[CCS IDE]] • [[PIC Microcontrollers with C18 Compiler|C18 Compiler]] • [[Debugging C on a PIC|Debugging]] • [[PIC computation time benchmarks|Benchmarks]]
|-
|'''Other''' || [[Stepper motor control with the PIC | Stepper motor control]] • [[PIC MCUs: Hardware and Connections | Hardware and Connections]] • [[Analog Output]]
|}

Digital inputs & outputs

2009-03-13T03:40:28Z

NealEhardt:

==Which pins are accessible on the 4520 prototyping board?==

[[Image:pinsbroughtout2.jpg|right]]

Most pins on the PIC are brought out to easily accessible lines on the 4520 board. Feel free to connect to the few others as well.

Do not drive any pin outside the range 0 to 5 volts, which can damage the PIC.

Most pins have several possible different input or output purposes, as evidenced by several names. Your software determines which purpose is in effect.

===Digital I/O pins (five "ports")===

[[Image:4520pindiagramdigitalports.jpg|right]]

With the exception of the positive voltage supply and ground pins, all pins on the PIC18F4520 can be used as digital I/O, however a few other pins (shown in gray below) are commonly utilized for communication instead of for digital I/O.

==Demo circuit for digital inputs and outputs==

[[Image:Digitalio.gif|right]]
The 4520 board has 32 1K resistors-to-ground built in, and spaces for 32 LEDs to be inserted, as shown in the circuit below You can see that the resistors are isolated from and have no effect on the PIC unless the LED is inserted.

At right is a demo circuit for digital input and digital output. Two LEDs have been inserted, and a pull-up switch and 4.7K pull-down resistor added.

Pin C1 is intended as a digital input, and will be designated so in software. When pushbutton switch S1 is depressed, it brings input C1 high, and the left LED illuminates. Otherwise input C1 is held low by the 4.7K resistor to ground. (The LED and its resistor cannot be counted upon to hold input C1 low.)

Pin D7 is intended as a digital output. When the PIC drives it high, the right LED illuminates, and otherwise not.

==Sample code==

[http://peshkin.mech.northwestern.edu/pic/code Link to all sample code here.]

The code digitalio.c is a complete C program that will compile and run.

You can read or write one bit at a time, or a whole 8-bit port as a byte. The demo code illustrates the functions input_c() which reads the whole C port as a byte (and returns an int8 value) and output_d(value) which writes to the whole D port as a byte (and takes an int8 argument).

You can also read a single pin using input(PIN_C4) which returns 1 or 0. PIN_C4 and its siblings are defined in the 18f4520.h "include" file.

For output to a single pin, you can use output_high(PIN_D7) and output_low(PIN_D7) which drive pin D7 high or low, or you can set it to a value in a variable with output_bit(PIN_D7, value) where value is 1 or 0.

All of the above built-in functions include instructions to set the targeted port or pin to digital input mode or digital output mode. That takes a few extra microseconds every time the function is called. It is possible to turn this part of the function code off, if you take responsibility to set the direction of the port or pin yourself.

switch bounce - most mechanical switches "bounce" which means they open and close several times when activated, over a period of a few mS. If this is a problem for your software, there are a lot of ways to debounce switches electronically. Better, write your software so it doesn't get confused by multiple open-close cycles.

==See also==
*[[PIC18F4520: Digital Inputs]]
*[[PIC18F4520: Digital Outputs]]

Digital inputs & outputs

2009-03-13T03:39:32Z

NealEhardt:

[[Image:pinsbroughtout2.jpg|right]]

==Which pins are accessible on the 4520 prototyping board?==

Most pins on the PIC are brought out to easily accessible lines on the 4520 board. Feel free to connect to the few others as well.

Do not drive any pin outside the range 0 to 5 volts, which can damage the PIC.

Most pins have several possible different input or output purposes, as evidenced by several names. Your software determines which purpose is in effect.

[[Image:4520pindiagramdigitalports.jpg|right]]

===Digital I/O pins (five "ports")===

With the exception of the positive voltage supply and ground pins, all pins on the PIC18F4520 can be used as digital I/O, however a few other pins (shown in gray below) are commonly utilized for communication instead of for digital I/O.

==Demo circuit for digital inputs and outputs==

[[Image:Digitalio.gif|right]]
The 4520 board has 32 1K resistors-to-ground built in, and spaces for 32 LEDs to be inserted, as shown in the circuit below You can see that the resistors are isolated from and have no effect on the PIC unless the LED is inserted.

At right is a demo circuit for digital input and digital output. Two LEDs have been inserted, and a pull-up switch and 4.7K pull-down resistor added.

Pin C1 is intended as a digital input, and will be designated so in software. When pushbutton switch S1 is depressed, it brings input C1 high, and the left LED illuminates. Otherwise input C1 is held low by the 4.7K resistor to ground. (The LED and its resistor cannot be counted upon to hold input C1 low.)

Pin D7 is intended as a digital output. When the PIC drives it high, the right LED illuminates, and otherwise not.

==Sample code==

[http://peshkin.mech.northwestern.edu/pic/code Link to all sample code here.]

The code digitalio.c is a complete C program that will compile and run.

You can read or write one bit at a time, or a whole 8-bit port as a byte. The demo code illustrates the functions input_c() which reads the whole C port as a byte (and returns an int8 value) and output_d(value) which writes to the whole D port as a byte (and takes an int8 argument).

You can also read a single pin using input(PIN_C4) which returns 1 or 0. PIN_C4 and its siblings are defined in the 18f4520.h "include" file.

For output to a single pin, you can use output_high(PIN_D7) and output_low(PIN_D7) which drive pin D7 high or low, or you can set it to a value in a variable with output_bit(PIN_D7, value) where value is 1 or 0.

All of the above built-in functions include instructions to set the targeted port or pin to digital input mode or digital output mode. That takes a few extra microseconds every time the function is called. It is possible to turn this part of the function code off, if you take responsibility to set the direction of the port or pin yourself.

switch bounce - most mechanical switches "bounce" which means they open and close several times when activated, over a period of a few mS. If this is a problem for your software, there are a lot of ways to debounce switches electronically. Better, write your software so it doesn't get confused by multiple open-close cycles.

==See also==
*[[PIC18F4520: Digital Inputs]]
*[[PIC18F4520: Digital Outputs]]

PIC computation time benchmarks

2009-03-10T22:51:48Z

NealEhardt: /* Circuit */

== Overview ==

The goal of this task is to determine the speed at which the [http://hades.mech.northwestern.edu/wiki/index.php/4520_Board_intro PIC 18F4520] (with 20MHz clock) makes certain calculations. There are many different ways to calculate common functions, such as Taylor expansion versus using the sine command. Some of these methods are faster than others, which could effect your program. When a program is dependent on time, such as while using an interrupt service routine for dead reckoning, a slower calculation might not complete within the ISR. Therefore, it is important to use the most efficient method for simple math and trigonometric functions. The following is empirical data of the speed to which certain data types conduct functions.

The process involved programming the function onto a PIC from a PC and using an oscilloscope to measure the time it took to complete. First, we checked to see if our procedure was free of errors. This was done by programming in a simple delay (e.g., 10μs to 50ms) and measuring its accuracy using the cursor feature on the oscilloscope. A digital output was used. The program would output high, run the delay, output low and run another delay. This would effectively display a square wave, where each delay should represent either the logic low or high on the scope. We found no error in our procedure. We then replaced a delay with a function (e.g., 2 + 5). Eventually we changed the code to conduct the function ten times consecutively. This was done to make oscilloscope measurement easier. The number of iterations of the function corresponded linearly with the time, so the time it took to do one function equated to ten times longer for ten functions, or one hundred times longer for one hundred functions. Our findings are summarized below.
 

== Circuit ==
[[Image:circuit_diagram.bmp|thumb|400px|Circuit Diagram]]
The circuit to conduct this test required the PIC 18F4520, power source and an oscilloscope hooked up to a digital output & ground. In the example below the wall power source was used, but a battery could be interchanged. The serial connection was used to update the PIC with each new test written with PIC-C on a nearby PC.

An example of an oscilloscope reading can be seen below right. Test readings were accurate with 1, 10 and 100 iteration tests. The cursor function was used to measure the duration of the high output.

[[Image:pic_configuration.jpg|thumb|500px|left|Circuit Configuration]]
[[Image:example_oscilloscope_reading.jpg|thumb|400px|right|Example of Oscilloscope Reading]]

 

== Code ==
<pre>
#include <18f4520.h>
#include <math.h>
#fuses HS,NOLVP,NOWDT
#use delay (clock=20000000)
#define LED_0 PIN_D0

void main(void) {

float z;
float x=0;
float y;
float xsquared, xcubed, xfifth, xseventh, xninth;

while(TRUE){

output_high(LED_0); // Do not use loop for the calculations because it will take time to iterate

//ninth order Taylor series (sine). Multiply by 1/n! instead of dividing by n! (multiplication is faster)

xsquared = x*x; //use these variables to keep calculation time down (instead of x*x*x*x*x....)
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333) - (xseventh*.0001984127) + (xninth*.00000275573);

/*
z = x + y; // code for simple math, change operations and variable types
z = x + y;
z = x + y;
z = x + y;
z = x + y;
z = x + y;
z = x + y;
z = x + y;
z = x + y;
z = x + y;

*/

output_low(LED_0);

//seventh order Taylors series (sine)

xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);
xsquared = x*x;
xcubed=xsquared*x;
xfifth=xcubed*xsquared;
xseventh=xfifth*xsquared;
xninth=xseventh*xsquared;
z = x - (xcubed*0.1666666) + (xfifth*.008333333);

/*

z = sqrt(x); //square root test
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);
z = sqrt(x);

*/

}
}
</pre>

== Results ==

=== Simple Math Functions ===

The below table contains the results from our operation testing. All the values are given in μs and the value in parentheses is the time normalized to the quickest operation in the entire table.

<table border="1" width="100%">
<tr>
<td width="12.5%">
Function
</td>
<td width="12.5%">
Int8
</td>
<td width="12.5%">
Int16
</td>
<td width="12.5%">
Int32
</td>
<td width="12.5%">
Signed Int8
</td>
<td width="12.5%">
Signed Int16
</td>
<td width="12.5%">
Signed Int32
</td>
<td width="12.5%">
Float
</td>
</tr>
<tr>
<td width="12.5%">
Addition (+)
</td>
<td width="12.5%">
0.64μs (1.00)
</td>
<td width="12.5%">
1.24μs (1.94)
</td>
<td width="12.5%">
2.44μs (3.81)
</td>
<td width="12.5%">
0.64μs (1.00)
</td>
<td width="12.5%">
1.24μs (1.94)
</td>
<td width="12.5%">
2.44μs (3.81)
</td>
<td width="12.5%">
25.6μs (40.00)
</td>
</tr>
<tr>
<td width="12.5%">
Subtraction (-)
</td>
<td width="12.5%">
0.68μs (1.06)
</td>
<td width="12.5%">
1.28μs (2.00)
</td>
<td width="12.5%">
2.48μs (3.88)
</td>
<td width="12.5%">
0.68μs (1.06)
</td>
<td width="12.5%">
1.28μs (2.00)
</td>
<td width="12.5%">
2.48μs (3.88)
</td>
<td width="12.5%">
29.8μs (46.56)*
</td>
</tr>
<tr>
<td width="12.5%">
Multiplication (*)
</td>
<td width="12.5%">
0.8μs (1.25)
</td>
<td width="12.5%">
6.0μs (9.38)
</td>
<td width="12.5%">
45.0μs (70.31)
</td>
<td width="12.5%">
0.92μs (1.44)
</td>
<td width="12.5%">
6.0μs (9.38)
</td>
<td width="12.5%">
46.0μs (71.88)
</td>
<td width="12.5%">
26.0μs-28.0μs (40.63-43.75)
</td>
</tr>
<tr>
<td width="12.5%">
Division (/)
</td>
<td width="12.5%">
19.4μs (30.31)
</td>
<td width="12.5%">
60.8μs (95.00)
</td>
<td width="12.5%">
195.0μs (304.69)*
</td>
<td width="12.5%">
22.4μs (35.00)
</td>
<td width="12.5%">
64.4μs (100.63)
</td>
<td width="12.5%">
201.0μs (314.06)*
</td>
<td width="12.5%">
176.0μs-226.0μs (275.00-353.13)
</td>
</tr>
<tr>
<td width="12.5%">
And (&)
</td>
<td width="12.5%">
0.64μs (1.00)
</td>
<td width="12.5%">
1.24μs (1.94)
</td>
<td width="12.5%">
2.44μs (3.81)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Or ( | )
</td>
<td width="12.5%">
0.68μs (1.06)
</td>
<td width="12.5%">
1.28μs (2.00)
</td>
<td width="12.5%">
2.48μs (3.88)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (>>1)
</td>
<td width="12.5%">
0.64μs (1.00)
</td>
<td width="12.5%">
1.04μs (1.63)
</td>
<td width="12.5%">
1.84μs (2.88)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (>>2)
</td>
<td width="12.5%">
1.04μs (1.63)
</td>
<td width="12.5%">
1.64μs (2.56)
</td>
<td width="12.5%">
2.84μs (4.44)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (>>3)
</td>
<td width="12.5%">
1.24μs (1.94)
</td>
<td width="12.5%">
2.04μs (3.19)
</td>
<td width="12.5%">
3.64μs (5.69)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (<<1)
</td>
<td width="12.5%">
0.68μs (1.06)
</td>
<td width="12.5%">
1.08μs (1.69)
</td>
<td width="12.5%">
1.88μs (2.94)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (<<2)
</td>
<td width="12.5%">
1.08μs (1.69)
</td>
<td width="12.5%">
1.68μs (2.63)
</td>
<td width="12.5%">
2.88μs (4.50)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
<tr>
<td width="12.5%">
Shift (<<3)
</td>
<td width="12.5%">
1.28μs (2.00)
</td>
<td width="12.5%">
2.08μs (3.25)
</td>
<td width="12.5%">
3.68μs (5.75)
</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
<td width="12.5%">


</td>
</tr>
</table> 
Table 1.1 Simple Math Functions
( * Indicates an averaged field)

As you can see, there are clear advantages to using smaller data types. There are even some operations that take slower with signed data types versus unsigned. Most all of the data was constant for small and large values for these simple math operations. For float data types, differing values tended to vary in time. Variability was also seen in some int32 calculations. These results are either given as an experimental range (if significant variability) or averaged (less than 4% variability).

Chapter 8 of the [http://129.105.69.13/datasheets/Microcontrollers/PIC18F4520.pdf PIC manual] lists the computation time for several multiply operations. Table 1.2 shows the values from the PIC manual compared to our measurements. As you can see, the calculation times are within an order of magnitude from each other. One difference is that in our measurements signed and unsigned multiplication took nearly the same amount of time. This was unexpected as the algorithm for signed multiplication (as outlined in the PIC manual) should take longer than unsigned multiplication.

 
<table border="1" width="52.5%">
<tr>
<td width="17.5%">
Routine
</td>
<td width="17.5%">
Time at 20 MHz clock speed*
</td>
<td width="17.5%">
Measured Values
</td>
</tr>

<tr>
<td width="12.5%">
int8 x int8 (unsigned)
</td>
<td width="12.5%">
0.2 us
</td>
<td width="17.5%">
0.8 us
</td>
</tr>

<tr>
<td width="12.5%">
int8 x int8 (signed)
</td>
<td width="12.5%">
1.2 us
</td>
<td width="17.5%">
0.92 us
</td>
</tr>

<tr>
<td width="12.5%">
int16 x int16 (unsigned)
</td>
<td width="12.5%">
5.6 us
</td>
<td width="17.5%">
6.0 us
</td>
</tr>

<tr>
<td width="12.5%">
int16 x int16 (signed)
</td>
<td width="12.5%">
8.0 us
</td>
<td width="17.5%">
6.0 us
</td>
</tr>

</table> 
Table 1.2 Multiplication times compared to PIC manual values (* Times derived from Table 8-1 of PIC manual)

=== Multiplication, Division & Shifts ===

For most integer types shifting is much quicker than multiplication and division. The exception is shifting more than one place for Int8 will take slightly longer. Therefore, if you are multiplying by 2# (where # is any positive integer value) it is faster to use a shift. The same is true if you are dividing by any factor of 2#. In this case shifting to the right divides and vice versa for multiplication.

Division is much slower than multiplication across all data types. If you are computing a float it is much faster to multiply by a reciprocal. Below is a table of two functions that compute the same value but at very different speeds.

<table border="1" width="35%">
<tr>
<td width="17.5%">
Function
</td>
<td width="17.5%">
Time
</td>
</tr>
<tr>
<td width="17.5%">
2 * 0.1
</td>
<td width="17.5%">
28μs (1.00)
</td>
</tr><tr>
<td width="17.5%">
2 / 10
</td>
<td width="17.5%">
200μs (7.14)
</td>
</tr><tr>
<td width="17.5%">
2* 0.001
</td>
<td width="17.5%">
28μs (1.00)
</td>
</tr><tr>
<td width="17.5%">
2 / 1000
</td>
<td width="17.5%">
220μs (7.86)
</td>
</tr>
</table> 
 

=== Trigonometric Functions & Square Root ===

Table 1.3 shows the results from the trigonometric, square root, and [http://en.wikipedia.org/wiki/Taylor_expansion Taylor Expansion] tests. The Taylor expansion example below is a ninth order. To conduct seventh or fifth order expansions one just drops out the higher terms. Sine and cosine functions take about the same time with tangent being slightly slower. Also, the square root function was slightly slower than the sine function. Note that the fast cosine value (0.24 ms) was for cos(0). Other than this value the time range closely matches that for sine. As shown the Taylor series approximation for sine is faster than using the sine command. It is important to note from our code that we multiplied by a reciprocal. Computing a Taylor series with division takes just a long as using the sine function. As expected, a higher order approximation will take more time. Depending on the amount of accuracy you need, using the Taylor approximation will save a significant amount of time.

[[Image:Taylor_Expansion_9th_Order.bmp|thumb|300px|left|[[Taylor Expansion 9th Order]]]]

 
<table border="1" width="52.5%">
<tr>
<td width="17.5%">
Function
</td>
<td width="17.5%">
Time Range (normalized)
</td>
<td width="17.5%">
Error
</td>
</tr>

<tr>
<td width="12.5%">
Sin
</td>
<td width="12.5%">
0.27-1.20 ms (3.80-16.9)
</td>
<td width="17.5%">
0
</td>
</tr>

<tr>
<td width="12.5%">
Sin (Taylor-9th order)
</td>
<td width="12.5%">
0.106-0.380 ms (1.49-5.35)
</td>
<td width="17.5%">
0.006925
</td>
</tr>

<tr>
<td width="12.5%">
Sin (Taylor-7th order)
</td>
<td width="12.5%">
0.089-0.312 ms (1.25-4.39)
</td>
<td width="17.5%">
0.07522
</td>
</tr>

<tr>
<td width="12.5%">
Sin (Taylor-5th order)
</td>
<td width="12.5%">
0.071-0.252 ms (1.00-3.55)
</td>
<td width="17.5%">
0.5240
</td>
</tr>

<tr>
<td width="12.5%">
Cos
</td>
<td width="12.5%">
0.24-1.14 ms (3.38-16.1)
</td>
<td width="17.5%">
n/a
</td>
</tr>

<tr>
<td width="12.5%">
Tan
</td>
<td width="12.5%">
1.37-2.52 ms (19.3-35.5)
</td>
<td width="17.5%">
n/a
</td>
</tr>

<tr>
<td width="12.5%">
Sqrt
</td>
<td width="12.5%">
0.98-1.26 ms (13.8-17.7)
</td>
<td width="17.5%">
n/a
</td>
</tr>
</table> 
Table 1.3 Trigonometric Functions and Square Root (all measurements are for float variables)

=== Algorithms for Square Root and Trigonometric Functions ===
There are several algorithms that can be used to compute the square root. The basic steps are:

: 1. Start with an initial guess, ''x''''0''.
: 2. Multiply ''x''''0'' by itself (or perform a different calculation).
: 3. See how close this solution is to the argument.
: 4. Change ''x''''0'' and iterate until you are close enough to the argument.

One such algorithm is the [http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method Babylonian method]. The way the PIC chooses the initial value, ''x''''0'', can affect the speed of the calculation. One way of choosing ''x''''0'' is to set it equal to <math>2^{\left\lfloor D/2\right\rfloor}</math> with D equal to the number of binary digits in the argument. The closer ''x''''0'' is to the actual answer the faster the computation will be. This is why there is a range for computation times because the initial value the PIC chooses will affect the algorithm speed. The algorithm also conducted an initial test of validity. Values less than zero were immediately rejected, because this algorithm does not compute imaginary numbers. We also noticed that very large numbers (we tried 1017) were also rejected. This initial validity test also contributes to slower calculation speeds.

One method that the PIC can use to calculate trigonometric functions is the [http://en.wikipedia.org/wiki/CORDIC CORDIC algorithm].
CORDIC is a type of shift-and-add algorithm that rotates a vector. An initial vector, ''v''''0'', is set and then multiplied by a rotation matrix. The rotation of the vector is repeated until its angle is close to the desired angle, <math> \theta </math>. The sine of <math> \theta </math> is the vector's projection onto the y-axis, while the cosine is the projection onto the x-axis. The number of iterations that the algorithm has to make depends on the angle, <math> \theta </math>. Thus, the PIC's computation time for trigonometric functions will vary depending on the angle.

Template:PIC

2009-03-10T21:08:37Z

NealEhardt:

{| border="2" cellpadding="6" width="100%"
!colspan="2" style="background:#efefef;" | [[PIC Microcontroller]]
|-
|'''[[PIC MCUs: Capabilities of PIC18F4520|PIC18F4520]]''' || width="100%" | [[Digital inputs & outputs|Digital I/O]] • [[PIC18F4520: Analog Inputs|Analog Input]] • [[PIC18F4520: PWM Motor Control|PWM Motor Control]] • [[PIC MCUs: 4520 Board|4250 Board]] • [[Sample code for most PIC18F4520 operations|Sample code]]
|-
|'''General Communication''' || [[PIC RS232|RS232 (Serial)]] • [[SPI - Serial Peripheral Interface - on the PIC|SPI]]
|-
|'''Inter-Pic Communication''' || [[I2C communication between PICs|I2C]] • [[IR communication between PICs|IR]] • [[SPI communication between PICs|SPI]] • [[XBee radio communication between PICs|XBee]]
|-
|'''Coding''' || [[PIC Microcontrollers with CCS Compiler|CCS Compiler]] • [[CCS IDE]] • [[PIC Microcontrollers with C18 Compiler|C18 Compiler]] • [[Debugging C on a PIC|Debugging]] • [[PIC computation time benchmarks|Benchmarks]]
|-
|'''Other''' || [[Stepper motor control with the PIC | Stepper motor control]] • [[PIC MCUs: Hardware and Connections | Hardware and Connections]] • [[Analog Output]]
|}

Machine Vision Localization System

2009-03-07T23:12:08Z

NealEhardt: /* Computer Setup */

__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. Install Microsoft Visual Studio Professional (Express Edition is incompatible with some of the code)

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.

Machine Vision Localization System

2009-03-07T23:11:23Z

NealEhardt: /* Computer Setup */

__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. Install Microsoft Visual Studio Professional

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.

PIC PWM Motor Driver

2009-02-10T18:25:23Z

NealEhardt: /* Overview */

==Overview==

DO NOT USE THIS PAGE. USE [[PIC18F4520: PWM Motor Control|THE OTHER PWM PAGE]].

This motor controller was designed for use as cheap, simple motor controller for [[Brushed DC Motor Theory|brushed DC motors]]. It uses a [[PIC Microcontroller]] to convert a low-power analog control signal to a [[Pulse Width Modulation|PWM]] duty cycle which is amplified using a full-bridge to drive a motor. A block diagram of this is shown below. This document gives the circuitry and programming needed to make such a controller.

[[image:PIC PWM block.png|center]]

==PIC PWM==

The first thing you need is a PIC microcontroller set up to convert an analog input to a PWM signal. The PIC used here is the [[PIC16F684]]. It only has one input, the analog control signal. It has two outputs: two opposite pulse width modulated pulse trains. The two PWM signals activate the two halves of the H-bridge to control the direction of the motor.

===PIC Code===

Code can be downloaded [[media:picpwmcode.zip|'''here''']].

The zip file contains the following files:

* main.asm - the program
* macros.inc - contains macros (quick code)
* PIC16F684.INC - assigns names to register addresses
* PICPWM.mcw and PICPWM.mcp - MPLAB workspaces

==Circuit==

The circuit consists of the PWM-enabled PIC chip, an amplifier and some protection circuitry. There are two versions of the circuit, one for low-power motors (1A continuous) and one for high-power motors (4A continuous).

===Low Power===

The low-power circuit uses the L293B push-pull driver ([[media:L293.pdf|datasheet]]). This circuit can be used for the 6W Maxon motors in the lab.

[[image:PIC PWM L293.png|center]]

[[image:PIC PWM L293 CIRCUIT.jpg|center|400px]]

===High Power===

A more high-power circuit makes use of the L298N ([[media:L298N.pdf|datasheet]]) full bridge amplifier.

[[image:PIC PWM L298.png|center]]

===Signal Conditioner (Optional)===

There is a problem with leaving out the signal conditioner part of the circuit. Sure you can program your controller to output your control signal scaled to 0 to +5v, but when it will likely reset to 0v at some point. 0v to the PIC corresponds to full speed in one direction. You want 0v to the circuit to mean 0 speed to the motor, or 0v (IN) = 2.5v (PIC). For this you can build a simple op-amp circuit.

[[image:PWM PIC Input Conditioner.png|center]]

[[image:PWM PIC Input Circuit.jpg|400px|center]]

This circuit can accomodate inputs of either <math>\pm\,</math>5V or <math>\pm\,</math>10V. The two potentiometers can be adjusted to give the correct gain. Diodes were added to protect the PIC from too low or too high voltage inputs.

Another way around this is to add an enabling input. Whenever the controller isn't running, the circuit can be disabled so the motors won't be accidentally driven in either direction.

==PCB Example==

You can download CircuitMaker and TraxMaker files here for this circuit using the L293. The PCB design is shown below. It is not optimized for space, but to be easy to read. You can edit it as you like. It is suited to use with the PC/104 stack.

* [[media:PIC PWM Circuit Files.zip]]

[[image:PIC PWM Traxmaker.jpg|center|400px]]

==TO DO==

# Find out why circuit causes motors to make high-pitch noise.
# Add "brake" functionality to the PIC. This will require at least one additional input. For example, a single digital input pin could cause the motor to "brake" when it's set high. To "brake", the PIC will have to disable the PWM mode and set the two output pins equal to eachother.
# Add "sensing" capability for better control.