Coap resources

Resource definition

Resources are easily defined using predefined macros that take care of all the boilerplate code.
For each resources, you simply have to define its name, path, interface description, resource type and the actual code to provide the data.
For periodic resources you have to also provides the period. For actuator, you have to provide the callback function performing the action.

Path, interface description and resource type can be freely chosen or may follow IPSO profile and CoAP Interface recommendations, see IPSO Profile.

Simple resource :

REST_RESOURCE(resource_name, ignore, resource_path, resource_if, resource_type, format)

Periodic resource :

REST_PERIODIC_RESOURCE(resource_name, resource_period, resource_path, resource_if, resource_type, format)

Event resource :

REST_EVENT_RESOURCE(resource_name, ignore, resource_path, resource_if, resource_type, format)

Actuator resource :

REST_ACTUATOR(resource_name, ignore, resource_path, resource_if, resource_type, format, actuator)

Formatting

The COAP resources library provides macros to convert resource data into the required format according to the defined content-type (see next chapter) :

Simple integer

These macros take the resource name as first parameter and the resource value as second parameter

REST_FORMAT_ONE_INT(resource_name, resource_value)
REST_FORMAT_ONE_UINT(resource_name, resource_value)
REST_FORMAT_ONE_LONG(resource_name, resource_value)
REST_FORMAT_ONE_ULONG(resource_name, resource_value)

Decimal value

This macro takes the resource name as first parameter, then the raw value of the resource, then two macros or function converting the raw value into its integer part and decimal part.

REST_FORMAT_ONE_DECIMAL(resource_name, sensor_value, resource_value_int, resource_value_float)

Simple string

This macros takes the resource name as first parameter and the resource value as second parameter

REST_FORMAT_ONE_STR(resource_name, sensor_value)

Two simple integer

This macros takes the meta resource name as first parameter, then the first resource name and value as second and third parameters, and the second resource name and value as fourth and fifth parameters

REST_FORMAT_TWO_INT(resource_name, sensor_a_name, sensor_a_value, sensor_b_name, sensor_b_value)

Content-type

The COAP resources library provides three content/type :

• text/plain
• application/xml
• application/json

Switching from one to another is done transparently in the project-conf.h file. The following macro are provided to automatically format your resources :

REST_TYPE_TEXT_PLAIN
REST_TYPE_APPLICATION_XML
REST_TYPE_APPLICATION_JSON

Examples

The following code will instanciate a periodic resource, giving the solar light level with a period of 30 seconds.

REST_PERIODIC_RESOURCE(light_solar,
    30,
    "sen/solar",
    "core.s",
    "ucum:lx",
    REST_FORMAT_ONE_INT("solar", light_sensor.value(LIGHT_SENSOR_TOTAL_SOLAR)))

In coap-server.c, you must add the definition of the resource :

extern periodic_resource_t periodic_resource_light_solar;

And add the initialization of the sensor and the resource :

  SENSORS_ACTIVATE(light_sensor);
  rest_activate_periodic_resource(&periodic_resource_light_solar);

COAP server

6lbr-demo includes a coap-server instanciating the following resources :

• Device info :
  • version
  • uptime
  • battery level
• Sensors :
  • light
  • temperature
  • humidity
  • button
• Actuators :
  • leds

It uses configuration macros to easily enable/disable and configure theses resources without modifying the code. See Example 4: COAP Server