Documentation library

nRF5 SDK for Mesh v3.0.0

Application level OnOff server behavioral structures, functions, and callbacks. More...

Data Structures

struct  app_onoff_state_t
 Internal structure to hold state and timing information. More...
 
struct  app_onoff_server_t
 Application level structure holding the OnOff server model context and OnOff state representation. More...
 

Macros

#define APP_ONOFF_SERVER_DEF(_name, _force_segmented, _mic_size, _set_cb, _get_cb)
 Macro to create application level app_onoff_server_t context. More...
 

Typedefs

typedef void(* app_onoff_set_cb_t) (const app_onoff_server_t *p_server, bool onoff)
 Application state set callback prototype. More...
 
typedef void(* app_onoff_get_cb_t) (const app_onoff_server_t *p_server, bool *p_present_onoff)
 Application state read callback prototype. More...
 

Functions

void app_onoff_status_publish (app_onoff_server_t *p_server)
 Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic OnOff Status message. More...
 
uint32_t app_onoff_init (app_onoff_server_t *p_server, uint8_t element_index)
 Initializes the behavioral module for the generic OnOff model. More...
 

Detailed Description

Application level OnOff server behavioral structures, functions, and callbacks.

This module implements the behavioral requirements of the Generic OnOff server model.

The application should use the set callback provided by this module to set the hardware state. The hardware state could be changed by reflecting the value provided by the set callback on the GPIO or by sending this value to the connected lighting peripheral using some other interface (e.g. serial interface). Similarly, the application should use the get callback provided by this module to read the hardware state.

This module triggers the set callback only when it determins that it is time to inform the user application. It is possible that the client can send multiple overlapping set commands. In such case any transition in progress will be abandoned and fresh transition will be started if required.

Warning
To comply with the Mesh Model Specification test cases, the application must adhere to the requirements defined in the following sections:
  • Section 3.1.1 (Generic OnOff) and Section 3.3.1.2 (Generic OnOff state behaviour) of Mesh Model Specification v1.0.
  • Section 3.7.6.1 (Publish) of Mesh Profile Specification v1.0.

These requirements are documented at appropriate places in the module source code.

Macro Definition Documentation

◆ APP_ONOFF_SERVER_DEF

#define APP_ONOFF_SERVER_DEF (   _name,
  _force_segmented,
  _mic_size,
  _set_cb,
  _get_cb 
)
Value:
APP_TIMER_DEF(_name ## _timer); \
static app_onoff_server_t _name = \
{ \
.server.settings.force_segmented = _force_segmented, \
.server.settings.transmic_size = _mic_size, \
.p_timer_id = &_name ## _timer, \
.onoff_set_cb = _set_cb, \
.onoff_get_cb = _get_cb \
};

Macro to create application level app_onoff_server_t context.

Individual timer instances are created for each model instance.

Parameters
[in]_nameName of the app_onoff_server_t instance
[in]_force_segmentedIf the Generic OnOff server shall use force segmentation of messages
[in]_mic_sizeMIC size to be used by Generic OnOff server
[in]_set_cbCallback for setting the application state to given value.
[in]_get_cbCallback for reading the state from the application.

Definition at line 88 of file app_onoff.h.

Typedef Documentation

◆ app_onoff_set_cb_t

typedef void(* app_onoff_set_cb_t) (const app_onoff_server_t *p_server, bool onoff)

Application state set callback prototype.

This callback is called by the this module whenever application is required to be informed to reflect the desired OnOff value, as a result of the received SET message. Depending on the received Target OnOff value and timing parameters, this callback may be triggered after the delay+transition time is over or instantly after the delay if the Target OnOff value is 1, as required by the Mesh Model Specification v1.0.

Note: Since the behavioral module encapsulates functionality required for the compliance with timing behaviour, it is not possible to infer number of Generic OnOff Set messages received by the node by counting the number of times this callback is triggered.

Parameters
[in]p_serverPointer to __app_onoff_server_t [app_onoff_server_t] context
[in]onoffNew onoff value to be used by the application

Definition at line 131 of file app_onoff.h.

◆ app_onoff_get_cb_t

typedef void(* app_onoff_get_cb_t) (const app_onoff_server_t *p_server, bool *p_present_onoff)

Application state read callback prototype.

This callback is called by the app_model_behaviour.c whenever application onoff state is required to be read.

Parameters
[in]p_serverPointer to __app_onoff_server_t [app_onoff_server_t] context
[out]p_present_onoffUser application fills this value with the value retrived from the hardware interface.

Definition at line 141 of file app_onoff.h.

Function Documentation

◆ app_onoff_status_publish()

void app_onoff_status_publish ( app_onoff_server_t *  p_server)

Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic OnOff Status message.

This API must always be called by an application when user initiated action (e.g. button press) results in the local OnOff state change. Mesh Profile Specification v1.0 mandates that, every local state change must be published if model publication state is configured. If model publication is not configured this API call will not generate any error condition.

Parameters
[in]p_serverPointer to __app_onoff_server_t [app_onoff_server_t] context

◆ app_onoff_init()

uint32_t app_onoff_init ( app_onoff_server_t *  p_server,
uint8_t  element_index 
)

Initializes the behavioral module for the generic OnOff model.

Parameters
[in]p_serverPointer to the application OnOff server struture array.
[in]element_indexElement index on which this server will be instantiated.
Return values
NRF_ERROR_NULLNULL pointer is supplied to the function or to the required member variable pointers.
NRF_ERROR_INVALID_PARAMIf value of the server_count is zero, or other parameters required by lower level APIs are not correct.
Returns
Other return values returned by the lower layer APIs.