Extending A Data Model Tutorial

This article was written for version 2.3.0 of Core. Click here for the most recent version of the help center.

PolySync Core provides a set of data model modules that are commonly used to develop autonomous vehicles. The modules can be modified and extended to include new data types, structures, typedegs, custom messages, and trouble codes.

Provided data model modules include:

  • Control
  • Diagnostic Trouble Code (DTC)
  • Navigation
  • Sensor

In this tutorial, we will extend the DTC module to demonstrate how to extend the PolySync Core data model.

1. Extending the data model

The PolySync Core data model is defined using IDL files which are parsed by the provided pdm-gen tool. pdm-gen generates the C and C++ headers and libraries that are used by PolySync Core applications.

1.1 Add a DTC type

To extend the DTC data model, open the IDL file that ships with the PolySync Core release package, and add a new Diagnostic Trouble Code (DTC):

$ sudo gedit $PSYNC_HOME/modules/dtc/dtc.idl

PolySync Core has reserved the lower 32-bits of the available ps_dtc IDs. This means that custom DTCs must have an ID with a value of 4,294,967,296 <= x<= 18,446,744,073,709,551,615.

We will add a custom DTC to the IDL with our custom description and macro name:

/** @brief Ibeo Lux device has overheated and cannot operate.
* Data will not be reported until the temperature matches the normal operating range.
*/

const ps_dtc DTC_IBEO_LUX_OVERHEATED = 4294967296;

DTCs are intended to represent a specific state of an application. Rather than saying hardware error, a DTC could indicate very specifically that the Ethernet sensor is overheated. Another DTC could indicate that the mirror is dirty, and so on.

1.2 IDL file requirements

The IDL files used to define a PolySync data model conform to a subset of the OMG CORBA v3 2002 standard.

pdm-gen does not support the following features of the OMG CORBA standard:

  • module and interface keywords
  • #include directives
  • multidimensional arrays
1.2.1 Message naming requirements

When adding new messages and other data types to the data model use snake-case naming standards, for example ps_new_message_type_msg. The generated C++ data type names use camel-case naming.

If naming collisions are encountered pdm-gen post-fixes _cpp to the generated C++ data type associated with the defined type name.

2. Generate the data model

Once all changes have been saved, the PolySync Core PDM tool is used to generate the data model with the DTC built into the API. Navigate to a directory where you want to generate your pdm files and use pdm-gen to generate the data model files.

2.1 Running pdm-gen

$ mkdir pdm/
$ pdm-gen -c $PSYNC_HOME/modules/dtc/dtc.idl $PSYNC_HOME/modules/sensor/sensor.idl $PSYNC_HOME/modules/navigation/navigation.idl $PSYNC_HOME/modules/control/control.idl > pdm/version.txt
$ sudo cp -a pdm/*.so* /usr/lib

Applications need to be rebuilt against the new API files before the new DTC is available at runtime, and can be used to indicate the diagnostic status.

The same process can be applied to all but one of the data model modules to extend or add new types and messages. Because some of PolySync’s most basic functionaility relies on data types defined in the core module, modifications to core.idl are ignored.

2.2 Moving the generated files

To see all files that are generated, and where in the system they need to be copied run the pdm-gen application with the -h flag.

$ pdm-gen -h
...
generated files that need to be copied manually
directory:
    <file>                              -> <system-location>
    libpolysync_data_model.so           -> /usr/lib
    libpolysync_cpp_message_support.so  -> /usr/lib
    psync.h                             -> /usr/local/polysync/pdm
    psyncDcps.h                         -> /usr/local/polysync/pdm
    psyncSacDcps.h                      -> /usr/local/polysync/pdm
    psyncSplDcps.h                      -> /usr/local/polysync/pdm
    psync.idl                           -> no need to copy, used to generate libpolysync_data_model.so
    psyncSacDcps.c                      -> no need to copy, symbols are in libpolysync_data_model.so
    PolySyncDataModel.hpp               -> /usr/local/polysync/pdm

Conclusion

As you’ve worked through this tutorial, you’ve learned how to extend the DTC module to demonstrate how to extend the PolySync Core data model.