Mobility Virtual Environment - MoVE

Hello, world


Table of Contents:

  1. Overview and test types
  2. MoVE executable commands
  3. Configuration file setup in ./scenario
  4. Route preparation in ./routes
  5. Performing a simple experiment: hello, world
  6. Post-processing and computing all-to-all distances in Matlab
  7. Google Maps real-time visualization using Bokeh


1.0 Overview and test types

The MoVE virtual environment can be setup and operated with multi-vehicle, multi-modal scenarios with ground, surface, or air vehicles. Each vehicle, including pedestrians, may be a virtual vehicle model or represent a real vehicle moving in the real world with live updates from GPS positions over a cellular network.

Experiments can be performed in simulation-only, real-only, or mixed-mode real and virtual configurations.

Familiarity with Linux or Unix is helpful. MoVE is executed nearly entirely from the command-line. Launching 3 or 4 terminal windows improves the ease with which MoVE tests are executed multiple times.

Additional tools are included for pre-processing route waypoints, post-processing log files, and verifying GPS positions are streaming in over the cellular network.

For live GPS inputs, there are two smart-phone apps that can provide live GPS updates with position, velocity, and course-over-ground via udp/ip over the cellular network. Both apps are developed and maintained entirely separately from MoVE:

  1. For Android-based smart devices, the HyperIMU app can be configured to send GPS position, velocity, and course-over-ground using the cellular network.

  2. For iOS-based iPhones, the SensorLog app can be configured to send GPS position, velocity, and course-over-ground using the cellular network.

Multiple smart-phones, running either or both of these apps can be used to simultaneously stream live-GPS-follower positions to MoVE Core.

The various MoVE setup and runtime options are described briefly below.


2.0 MoVE executable commands

MoVE was developed with the Unix philosophy where specialized individual programs are combined to perform more complex operations as they interact.

There is no single executable to run and try with point-and-click. MoVE is a Python code base with individual command-line programs that interact together.

MoVE’s primary runtime components include:

Python script Description
main_launch_veh_process.py for launching N vehicle processes
main_changeRunState.py for changing runState to: Ready, Set, Go, Pause, Stop
main_core.py for aggregating all vehicle positions and logging State to a .csv file

There are also udp message receiving programs to test and verify iPhone or Android app communication. These test to ensure GPS positions are being received over the Wifi or cellular network connection. Familiarity with the basics of network messaging and firewalls will be helpful.

Also, there are waypoint pre-processor scripts in ./routes/preprocessing to help generate new waypoint routes for the followRoute() behavior.


3.0 Configuration file setup in ./scenario

The configuration files follow the MS Windows .ini format used in the Python configparser library.

The main sections in the scenario config file read by MoVE Core are:

Section Description
[common] parameters common to both Core and vehicle models such as number of virtual vehicle models (nVeh_builtin), live-GPS-followers nVeh_live_gps, and udp port assignments
[scenario] scenario-specific parameters
[core] logging frequency and other parmeters for MoVE Core
[veh_sim] simulation stepsize, communication interval, and other vehicle-oriented parameters
[veh_beh] boolean True/False flags to turn certain behaviors ON or OFF for all virtual vehicles
[veh_route_assignments] optional section for designating routes to particular vehicle IDs
[veh_names_builtins] vehicle names to help identify built-in vehicle models
[veh_names_live_gps] vehicle or people’s names to record role assignments during the experiment (who was where doing what?)


4.0 Route preparation in ./routes

To help debugging and isolate the source of code problems, each route definition file is designed to run as a stand-alone Python program.

If you cannot get the route definition file to run by itself there’s no reason to attempt integration with the MoVE vehicles.

The example route definition files in the ./routes directory can be used as templates for either math-oriented route definitions (circles, lines, and so on) or point-based route definitions.

Examples are provided with coordinate conversion from lat/lon/elev to Cartesian XYZ coordinates.

Point sequences can be provided as Cartesian XYZ coordinates or lat/lon/elev point sequences in geodetic coordinates (decimal degrees).

Each route file designates member entries in a route object:

Section Description
route.originalUnits ‘decimal_degrees’ or ‘meters’
route.desc brief description of the test, date and features
route.X waypoint X position (in meters for cartesian XYZ or decimal degrees in lat/lon/elev)
route.Y waypoint Y position
route.Z waypoint Z position
route.spd_mps speed command for each waypoint in (m/s)
route.source automatically assigned to the route file name

Get your route working at the command line just like the examples, then attempt to integrate the new route into the MoVE config file’s [veh_route_assignments] section.


5.0 Performing a simple experiment: hello, world

Once both Python test scripts (from Getting Started) report all favorable answers, once you’ve downloaded and unzipped the MoVE source code, and once your username can ssh to localhost without entering a password, open 4 terminal windows and arrange them as shown below:

My convention during development:

Terminal 3 (or another) is used to launch the Bokeh-based Google Maps visualization of vehicles zooming around. I typically move to a different virtual desktop (ctrl-alt-right or left) and open another terminal and web browser.

Change username:

Open ./scenario/default.cfg and change username to your machine’s username that can ssh into localhost wtihout a password. The username config entry is in the [common] section.

Test Sequence with 3 virtual vehicles:

Follow this test sequence using default.cfg to simulate 3 vehicles moving around with these behaviors: wander(), periodicTurn(), stayInBounds(), avoid().

  1. in Terminal 3: start ./main_core.py -f ../scenario/default.cfg
  2. in Terminal 1: launch vehicle models with ./main_launch_veh_process.py -f ../scenario/default.cfg
  3. step 2 launched N separate vehicle processes, each in it’s own screen processes.
  4. in Terminal 4: verify all vehicle model processes are running by running screen -ls This is what you should see in Terminal 4:
  1. vehicle model processes start by default in runState==1, or Ready.
  2. in Terminal 2: issue a runState=2 command with: ./main_changeRunState.py -f ../scenario/default.cfg 2
  3. this will advance all vehicle models toSet and place virtual vehicles at their initial conditions
  4. in Terminal 3: you should observe all vehicle models change from Ready to Set:
  1. in Terminal 2: issue a runState=3 command with: ./main_changeRunState.py -f ../scenario/default.cfg 3
  2. this will advance all vehicle models toGo! and begin numerical integration of equations of motion in soft-real-time
  3. in Terminal 3: you should observe all vehicle models change from Set to Go!:
  1. in Terminal 2: issue a runState=5 command with: ./main_changeRunState.py -f ../scenario/default.cfg 5
  2. this will cause all vehicle models to stop and exit.
  3. in Terminal 3: verify all vehicle models have exited with screen -ls
  4. in Terminal 4: press ctrl-c to exit MoVE Core

This concludes the hello, world test for MoVE.

A .csv file is left in /tmp that contains vehicle model time histories.

Verify with ls -lt /tmp | more. The most recent logfile will be sorted at the top.

The test logfile name contains the year-month-day and hour-minute-second it was created:

YYYY_MM_DD__HH_MM_SS_core_State.csv

Like this:


6.0 Post-processing and computing all-to-all distances in Matlab

To post-process the .csv file just created:

  1. copy the most recent .csv just created in /tmp into the ./core/postProc directory
  2. edit the Matlab post-processing script, postproc_core.m in ./core/postProc to use the most recent Core logfile, then run.
  3. Multiple Matlab figure windows of each vehicle’s time history, a Google Maps plot, and all-to-all vehicle distances are computed and plotted.


7.0 Google Maps real-time visualization using Bokeh

Repeat the hello, world exercise above using the same 4 figure windows. Use the up-arrow in each terminal window to repeat commands to launch Core, launch vehicle models, and advance the runState from the initial 1 (Ready), to 2 (Set), then 3 (Go).

When the vehicles are moving and Core is aggregating and logging all vehicle positions, it will also be sending udp/ip messages to a visualization client.

I typically go to another virtual window (using ctrl+alt+up-arrow or down-arrow or left/right arrow) to begin with an uncluttered desktop but this is not necessary.

Open another terminal window and change directories to the ./v1.05/bokeh_viz_client directory.

Issue this bokeh command to open a web browser and begin displaying the moving vehicles on top of a Google Maps overlay:

bokeh serve --show gps_move_live_mapping.py

You should see something like this with the 3 vehicles moving around on the Google Maps display:

To simulate more vehicles, change nVeh_builtin in config file, default.cfg.

To simulate other scenarios or different locations with different behaviors, you can explore and change default.cfg or copy default.cfg with another name and change the behaviors, number of vehicles, or change the viz update rate.

This concludes the MoVE Hello, world exercise.