Luos engine services profiles

What is a service profile

Now that you understand what a service and a service type are and how to create them, we can address the subject of profiles.

info

A service profile is pre-made API management for a specific service type. Basically, a profile gives a data structure with all variables you need to handle in the service. The profile code knows how to deal with those variables and share the service information with any other.

The profile handles messaging to share your variables with other services. Moreover, It updates them if a service writes into some of them. Thanks to this feature, your variables are shared with all the system in real-time without explicit message handling in the service code.

tip

Example: If you want to make a servo-motor service, you have to select the servo-motor profile for your service and use variables of the profile structure to set the rotor's current position measurement, or to get the current motor's target in your code.

Profiles are convenient for making your code clean and straightforward, complying with your development into a standard API, or sharing your service's type with the community. Luos engine provides some common profile models that you can use; feel free to contribute and to add your own to the standard profile bank with a pull request on Luos engine GitHub page ↗.

How to use a profile in your service

To use this feature, you have to import the profile corresponding to your needs and instantiate a structure it brings to you:

#include "profile_servo_motor.h"

profile_servo_motor_t servo_motor; // create a motor profile structure

Now that your structure exists, you can access all variables it embeds. But it will not be updated by Luos engine as described above, for this one step remains: you have to create a service and tell Luos engine that you are using a profile and that you want the platform to handle it for you.

So far, you learned to create a service with the Luos_CreateService() call, but we did not talk about giving information to the platform about the profile you instantiated. In fact, a function exists and can do this job for you. Every profile implementation for a specific type comes with a Profile_CreateService() function wich is similar to the Luos_CreateService() routine. It actually calls Luos_CreateService() and some other glue-routines to register your profile structure in the platform. For the motor profile, the dedicated routine is showed here:

service_t *ProfileServo_CreateService(profile_servo_motor_t *profile_servo_motor, SERVICE_CB callback, const char *alias, revision_t revision);

The returned service_t* is a service structure pointer that will be useful to make your service act in the network.

• callback is a pointer to the same callback function described in the service management section. The main difference between profile services and custom services is that you don't need to manage any message in this callback because the profile handles it for you. You can use this callback to make your code react to an event or manage custom messages on top of the profile.
• var is the profile structure pointer you just created.
• default alias is the alias by default for your new service, e.g. Myprofile02. This alias is the one your service will use if no other alias is set by the user of your functionality hosted in your service. Aliases have a maximum size of 16 characters.
• revision is the revision number of the service you are creating.

Following the packages rules, here is a code example for a button service using a state profile:

#include "profile_state.h"

template_state_t button_template;
profile_state_t *button = &button_template.profile;

void Button_Init(void)
{
    // service initialization
    revision_t revision = {.major = 1, .minor = 0, .build = 0};
    // Profile configuration
    button.access = READ_ONLY_ACCESS;
    // Service creation following state profile
    ProfileState_CreateService(&button, 0, "button", revision);
}

void Button_Loop(void) {
    button.state = (bool)HAL_GPIO_ReadPin(BTN_GPIO_Port, BTN_Pin);
}

You can notice that you did not send any Luos message to share the button's state: if an application wants to access this information, the state profile will share it for you. You only have to update the button's state value in your code. Supported profiles are available in this repository.