UAVObjects are the object containers of the UAVTalk Protocol.

In this page

Creating UAVObjects

The source code for UAVObjects is automatically generated for both the ground and flight software using the UAVObjectGenerator command line utility, this utility reads an XML definition of the object and its fields and generates the necessary autopilot and GCS source code.

UAVObjectGenerator Utility

The source code for the UAVObjectGenerator can be found at ground\uavobjgenerator, the most straight forward way to compile this source is by building it on the command line, all you need is a working Qt environment. For example, do this by performing the following:

make uavobjgenerator
The compiled binary (uavobjgenerator) will be located in the same folder (for GNU/Linux users). Executing the binary with the "-h" parameter will explain how to use the program (i.e. all the different parameters).

It is suggested it is run from this location, this way it will automatically look for xml files in the correct location and additionally output the files it generates in the right location for both the flight and GCS code.

Usually the UAVObjectGenerator and all UAVObjects for all platforms will be built with just this:

make uavobjects

XML File

The next step is to create the UAVObject definition file. All definition files are located in the shared\uavobjectdefinition directory. Each XML file defines at least a single object. An example file is shown below.

    <object name="GPSPositionSensor" singleinstance="true" settings="false" category="Sensors">
        <description>Raw GPS data from @ref GPSModule.</description>
        <field name="Status" units="" type="enum" elements="1" options="NoGPS,NoFix,Fix2D,Fix3D"/>
        <field name="Latitude" units="degrees x 10^-7" type="int32" elements="1"/>
        <field name="Longitude" units="degrees x 10^-7" type="int32" elements="1"/>
        <field name="Altitude" units="meters" type="float" elements="1"/>
        <field name="GeoidSeparation" units="meters" type="float" elements="1"/>
        <field name="Heading" units="degrees" type="float" elements="1"/>
        <field name="Groundspeed" units="m/s" type="float" elements="1"/>
        <field name="Satellites" units="" type="int8" elements="1"/>
        <field name="PDOP" units="" type="float" elements="1"/>
        <field name="HDOP" units="" type="float" elements="1"/>
        <field name="VDOP" units="" type="float" elements="1"/>
 <field name="SensorType" units="" type="enum" elements="1" 
options="Unknown,NMEA,UBX,UBX7,UBX8" defaultvalue="Unknown" />
 <field name="AutoConfigStatus" units="" type="enum" elements="1" 
options="DISABLED,RUNNING,DONE,ERROR" defaultvalue="DISABLED" />
 <field name="BaudRate" units="" type="enum" elements="1" 
defaultvalue="Unknown" />
        <access gcs="readwrite" flight="readwrite"/>
        <telemetrygcs acked="false" updatemode="manual" period="0"/>
        <telemetryflight acked="false" updatemode="periodic" period="1000"/>
        <logging updatemode="manual" period="0"/>

Object attributes

The object attributes define the name and type of the object.

The singleinstance attribute is used for objects that require multiple separate instances, the vast majority of the objects will be single instance objects. Settings attribute is used for objects that configure the OpenPilot firmware, these objects are saved to the SDCard and are loaded at boot by the autopilot, if you are creating a setting this attribute should be set to true.

The field entries define the properties of each field. The elements attribute is used to define array fields.

The access, telemetrygcs and telemetryflight entries are the object metadata. The metadata can also be changed at runtime and remotely by the GCS. The access entry is used to define the access mode of this object in the flight and ground code. Read-only objects can only be read, this is used when HITL simulation is enabled and allows for the local object updates to be ignored and instead replaced by remote updates. An example would be the PositionActual object, normally the flight access mode is readwrite and the object is updated by the GPS module in the flight code. However in HITL mode, we do not want the GPS module to write on the PositionActual object, instead the object should be updated by the GCS (since FlightGear is now generating the position data). In this mode the access mode in the flight code is set to readonly and the local GPS module updates are ignored (the module still runs as usual, it is the object updates that are ignored by the UAVObject library).

The telemetrygcs and telemetryflight entries are used by the telemetry modules. The acked attribute defines if object transactions should be acknowledged. The updatemode can be one of the following: periodic, onchange, manual and never. The periodic mode will send the object through the telemetry link at the interval defined in the period attribute (in ms). The onchange mode will send the object through the telemetry link only when it changes, care must be taken when this mode is used in frequently updated objects. In the manual mode the object will only be updated when requested remotely or locally.

Adding Your Object to the Build

Once the object definition file is created and copied in the shared\uavobjectdefinition directory and UAVObjectGenerator should be invoked with no arguments. The generator will process all XML files and generate the output files in the following directories, ground\uavobjects for the ground code and flight\UAVObjects for the flight code.

The last step would be to add the objects to the makefiles. For the ground software add the source files (.cpp and .h) to the <OP>/ground/openpilotgcs/src/plugins/uavobjects/ project file.

For the flight software it depends of board :

  • for coptercontrol target add .c file in  flight/target/board/<targetname>/Makefile
  • for revo and newer boards : update the flight/target/board/<targetname>/firmware/ 

Rebuild, reload and now you should be able to see the newly created object in the GCS UAVObject browser.