RAML to AGL

This is a Proof of Concept of a Model Driven Development approach to generate Automotive Grade Linux applications and services by defining their interfaces using RAML.

Architectural Design

The architectural design documentation can be reviewed, here.

Usage

raml2agl -i <model>.raml [-o <output_dir>] [-s <output_sources_dir>] [-h <output_headers_dir>] [-v] --app|--service

• -i <model>.raml: Path to the RAML model file
• -o <output_dir>: Directory where the generated source and header files will be stored.
• -s <output_sources_dir>: Directory where the generated source files will be stored. This parameter overrides -o.
• -h <output_headers_dir>: Directory where the generated header files will be stored. This parameter overrides -o.
• -v: Increases verbosity
• --app: Generates Application outcomes
• --service: Generates service outcomes

Install dependencies

To install the dependencies, simply run;

sudo apt-get install python-pip python-dev build-essential
pip install -r requirements.txt

Examples

The examples directory holds some examples of the output. Keep in mind that the app and service subdirectories hold the automatically generated code for the application and the AGL service side, respectively.

The application side is abstracted as a C++ class that performs the underlying requirements to communicate through the Web Socket with the Service. For instance, a simple interface with a setter and a getter can be modeled using RAML as follows;

#%RAML 1.0
title: Set Getter
/get:
  description: "Get Data"
  get:
    responses:
      200:
        body:
          type: integer

/set:
  description: "Setup"
  post:
    body:
      type: integer

This model can be found in examples/setget/setget.raml. To generate the output simply run;

cd <proj-root-dir>
python src/raml2agl.py -i examples/setget/setget.raml -o my_new_out --app

And will generate a C++ class at examples/my_new_out/include/app/SetGetter.h that looks as follows;

class SetGetter : public WebSocketApi {
public:

  SetGetter();

    /** Autogenrated doc for get */
    int get(int &out_default);

    /** Autogenrated doc for set */
    int set(const int in_default);

};

From it side the AGL service can also be generated by running;

cd <proj-root-dir>
python src/raml2agl.py -i examples/setget/setget.raml -o my_new_out --service

Similarly as with the SetGetter class raml2agl also generates the skeleton of the service side, which can be found at examples/setget/src/service/ServiceSetGetter.cpp and looks like;

/** Autogenrated doc for get */
int ServiceSetGetter::get(int &out_default) {

  AFB_NOTICE("[ServiceSetGetter] Get");
  AFB_ERROR("Method Get not implemented");

  return -1;
}

/** Autogenrated doc for set */
int ServiceSetGetter::set(const int in_default) {

  AFB_NOTICE("[ServiceSetGetter] Set");
  AFB_ERROR("Method Set not implemented");

  return -1;
}

Note that ServiceSetGetter class isn't implemented. Implement the actual service behavior within this file.

In order to abstract the communication mechanism raml2agl generates the the structures that the AGL application framework needs. This structures can be seen in the examples/setget/src/service/setgetter-binding-auto.cpp file and look like.

static const struct afb_verb_v2 verbs[] = {
  /*Without security*/
  {.verb = "setupsensor", .callback = setupsensor, .auth = NULL, .info = "Setup", .session = 0},
  {.verb = "getdata", .callback = getdata, .auth = NULL, .info = "Get Data", .session = 0},
  {.verb= NULL, .callback=NULL, .auth = NULL, .info = NULL, .session = 0 }
};

const struct afb_binding_v2 afbBindingV2 = {
  .api = "sensorinterface",
  .specification = "",
  .info = "Auto generated - Sensor Interface",
  .verbs = verbs,
  .preinit = NULL,
  .init = init,
  .onevent = NULL,
  .noconcurrency = 1
};

The examples/setget/src/service/setgetter-binding-auto.cpp is completely generated for your convenience. Fell free to review it's implemented to get more insight on how the communication takes place.

TODOs

• Add Doxygen documentation to the autogenerated files

• Add full support for RAML 1.0. Currently only the following features are supported:

  • Properties list
  • Only the response 200 is consider
  • Get and post in the same verb
  • Base URI specification

• Add pointer to a demo repository

• Add installing scripts

• Add unit testing

• Add more internal documentation in python scripts