• Device

Device

---

This Page describes how to implement a new device.

What is a device good for?#

A device is a container for data and functionality which resides in individual vehicles. Devices are notified about all vehicle movements and may interact with the vehicle or with other devices. An important aspect of devices is, that it is possible to equip only a fraction of the simulated vehicles. Usually devices support some kind of output. The following is a list of available devices and their functionality

MSDevice_Tripinfo#

Records start and arrival of a vehicle as well as aggregate measures about a completed trip such as average speed and waiting time. This device is also used for expressing aggregate results from other devices such as emissions (MSDevice_HBEFA). This devices is activated using the option --tripinfo-output <FILE> and is then active for all vehicles.

MSDevice_Vehroutes#

Records the edges traveled by a vehicle and optionally the times at which each edge was left. It can also record dynamic route changes. This device is also used for expressing aggregate results from other devices such as emissions (MSDevice_HBEFA). This devices is activated using the option --vehroute-output <FILE> and is then active for all vehicles.

MSDevice_Routing#

Triggers periodic rerouting of equipped vehicles. This devices is activated using the options --vehroute-output.* and is then active for selected vehicles. It is possible to equip specific vehicles or a fraction of the vehicle fleet.

MSDevice_Person#

This device is automatically created if a person rides in a vehicle. It is used when managing boarding and alighting

MSDevice_HBEFA#

Computes emissions of a vehicle as described in Definition_of_Vehicles,_Vehicle_Types,_and_Routes#Vehicle_Emission_Classes. This devices is activated using the options --device.hbefa.* and is then active for selected vehicles. It is possible to equip specific vehicles or a fraction of the vehicle fleet.

MSDevice_Battery#

This device is used for modelling energy use and battery capacity of electric vehicles.

MSDevice_SSM#

This device logs surrogate safety measures for equipped vehicles, see Simulation/Output/SSM_Device.

MSDevice_Example#

This device serves as an implementation example for custom devices.

Steps for implementing a new device#

Copy Example Device#

The suggested way for creating a new device is to create a new class by copying the files src/microsim/devices/MSDevice_Example.{h,cpp}.

In order to compile the new class it must be added to src/microsim/devices/Makefile.am (on Linux) or added to project z_libmicrosim_devices (on Windows).

In order to be available for use, the device must also be added in src/microsim/devices/MSDevice.cpp to the functions insertOptions and buildVehicleDevices.

Assign Device to Vehicles#

Devices are assigned by global options for equipping all or a fraction of the vehicle fleet. Alternatively, they can be defined by setting <vehicle> or <vType>-generic parameters. The new assignment options are generated automatically by calling the function MSDevice::insertDefaultAssignmentsOptions. The test whether a specific vehicle should be equipped with the device is done by calling MSDevice::equippedByDefaultAssignmentOptions. The usage of these methods is demonstrated in MSDevice_Example.

Adding your own functionality#

Devices work by updating their state periodically (i.e. MSDevice_Routing) or every time the vehicle moves (i.e. MSDevice_Battery). Many devices perform some kind of output either periodically (MSDevice_Routing) in response to computed events (MSDevice_BTreceiver) or at the time the vehicle leaves the simulation (MSDevice_Vehroutes). Before the vehicle is removed the method generateOutput is called for each device.

Testing your code#

Show your work#

If you have implemented a new device and you think it may be useful to other users of SUMO, please contribute to our community and tell us about your work. We would be happy to help you in getting your device into the main development tree.