Introduction | Parts and assembly | Software stack | Download manuscript | V3 Page
This page provides instructions on setting up the software stack (API) for programming over microMVP with a set of six vehicles. The API will enable the vehicles to follow specific paths but do not guarantee that the vehicles will not collide. However, we do provide a demo showing how six vehicles may be synchronized. These way point based APIs are sufficient for the vehicles to follow complex paths without collision. APIs enable more complex tasks will be gradually added as they are fully tested and ready. Toward the end of the page, instructions are provided on how to add additional vehicles to the system. The source files needed for this part can be downloaded here.
Note that this page is meant for an audience comfortable with python and is not intended for general educators. We plan to make more readily usable open source distributions available for primary and secondary education in the near future with plain, easy to follow instructions.
Packages to be installed
The following libraries should be installed before proceeding. We assume that the end user has basic knowledge when it comes to setting up these libraries for the purpose of program compilation.
OpenCV 2.x and up
We assume the user has boost library installed as well.
Enabling vehicle tracking
> detect-live.exe cameraID portFor example, running "detect-live.exe 0 5556" will use camera 0 (the first camera of the system) and starts feeding tag positions within the camera's range on port 5556. Note that for best tracking, one should adjust the camera parameters (using openCV or camera driver software if available) including exposure, brightness, contrast, white balance, and so on to make sure the tags within the camera range are consistently tracked (the number of tags seen by chilitags is displayed at the top left corner of the tracking app. See picture below for a screen shot of the module while running. Note that all six tags are tracked. We set the camera to run at 1280x720 resolution, which appears sufficient for the purpose of tracking. This can be set to 1920x1080 (in detect-live.cpp) if desirable.
Once the vehicle position data publisher is started, one may test the data feed using positionZMQSub.py under the python folder as (make sure that the parameters in globals.py are set according to your setup)
> python positionZMQSub.py tagIDin which tagID is the chilitag ID (displayed on the tracking program UI window) for a given vehicle. For example, suppose that a vehicle with tagID 29 is in the camera's range, then running python positionZMQSub.py 29 should produce an output like the following
Collecting update from server: tcp://192.168.1.10:5556
Flashing the xBees
The communication between the vehicles and the main control computer is done through xBees. We choose to put all xBees in the "AT" mode. For each xBee, set the channel and PAN ID to be the same and the baud rate at 57600. For example, a possible setting may be
CH Channel: 12
ID PAN ID: 2048
BD Interface data rate: 57600
Programming and testing the vehicle
The fio v3 based vehicle is fully compatible with Arduino and can be easily set up so that the vehicle can be programmed with the Arduino IDE. In the IDE, compile and upload the Arduino code (fio-v3-7-car-v1.ino) via the USB port on the fio v3 board. Note that for each vehicle, a different carID should be used. For six vehicles, these IDs should be 1-6. One should know which vehicle has which carID. Leave all other field to have the default values. Once this is done, when two such xBees are powered up, they can readily communicate with each other.
To test that a vehicle is indeed working fine, run xBee.py under the python folder as
> python xBee.py carIDin which carID is the ID of the vehicle (the same carID used in the .ino file when flashing the vehicle's fio v3). This should run the two wheels of the given car for 5 seconds before turning them off.
Putting it together
After the vehicles and the tracking platform are individually tested, it is time to put everything together. We start with a single vehicle. For this, we run singleController.py. In this python file, the carID (the one used in the .ino file for flashing the vehicle) and carTag (the chilitag ID attached to the vehicle) must match those of the actual car being tested. To run the module, simply fire it up
> python singleController.pyThis brings up a pygame based UI. Note that this UI is completely optional. In the UI, there should be a cartoon car representing the actual vehicle location (assuming that the vehicle with the correct ID is placed in the camera's range) as shown in the picture below (without the path).
A user may then use the mouse to draw an arbitrary path inside the UI and the vehicle should start following the path using the pure pursuit algorithm (see the picture above; the path is the one that is drwan using a mouse). Note that all key functionality resides in the class DDRCar.py, which allows both the simulation and real test of DDR vehicle. Roughly the logic flow looks like the following (we assume here that all way points are added in the beginning to make the illustration simple) for running on a real vehicle
in which carXBeeID is carID of the vehicle, wheelDist is the length between the
two wheel centers in screen pixels, multiplier*wheelDist is the lookahead
distance (for pure pursuit) in pixels, and throttle is a number between 0 and 1
that limits the top speed of the vehicle. The later two parameters are for
simulation with obviously meanings. It may happen that some vehicle has a
fast/slower speed given the same thrust input. If the difference is too big,
one may use throttle to adjust for it.
More complex patterns can be readily added by dissecting the pattern into a list of way points. In the python UI of singleController.py, press 'p' will cause the car to follow a circle for two full rotations (the screenshot below was captured when the car was following the circle).
The main logic of singleController.py, besides the UI part, is to separate the way point management from the running of the vehicle control. Other than this, the logic flow is straightforward and we leave it to the user to digest it.
Adding more vehicles (without considering collision) is also straightforward once a single vehicle works well. The file controller.py provides an example that can be executed similarly as
> python controller.pyThis module assumes that there are six vehicles with carID from 1 to 6 and different chilitag IDs property setup in controller.py near the beginning of the file. The UI looks like the following
controller.py allows the selection of active vehicle by pressing the keyboard key corresponding to the vehicle's ID. After a vehicle is selected, one may draing an arbitraray path for the vehicle to follow similar to the single vehicle case. Multiple vehicles may move simultaneously. As we have already mentioned, collision is not automatically handled. The console output and the screenshot are provided below.
Collecting update from server: tcp://localhost:5556
Similarly, one may program all six vehicles to move synchronously. The sychronization is performed via speed adjustments based on the individual vehicles progress in reaching way points. To avoide collision, the vehicles should be placed roughly as given in the following figure
Pressing the keyboard key "c" then should cause the vehicles to synchronously follow a circle, evenly spaced, for two full circles.
Adding even more vehicles
There are many ways of adding more vehicles to the system. The simplest one is to use a single xBee to talk to all vehicles. In the provided code, vehicle thrusts are sent in 16 byte blocks. The block is identified by the frist and last byte. The middle 14 bytes are wheel thrusts for 7 vehicles. Making this block longer will then allow more vehicles to be added.
The slight downside with the above approach is that as more and more vehicles are added, there can be interference between the xBees. This can be mitigated by limiting the number of xBees on the same channel. Both approaches require updating the Arduino code and xBee.py. Our experiments show that either approcah seems to work fine with 15-20 vehicles.
Return to top