Light Control

Detailed Description

Light Control object implementation for LwM2M client using Wakaama

Warning

This feature is experimental!
This API is considered experimental and may change in future releases without deprecation process.

This implements the LwM2M Light Control object (ID 3311) as specified in the LwM2M registry.

This Object is used to control a light source, such as a LED or other light. It allows a light to be turned on or off and dim it.

To use this object add USEMODULE += wakaama_objects_light_control to the application Makefile.

Resources

For an XML description of the object see https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/3311.xml

Name	ID	Mandatory	Type	Range	Units	Implemented
On/Off	5850	Yes	Boolean	-	-	Yes[1]
Dimmer	5851	No	Integer	0 - 100	/100	Yes[1]
On time	5852	No	Integer	-	s	Yes
Cumulative active power	5805	No	Float	-	Wh	No
Power factor	5820	No	Float	-	-	No
Colour	5706	No	String	-	-	Yes
Sensor Units	5701	No	String	-	-	No
Application Type	5750	No	String	-	-	Yes

[1]: The handling of these resources are implemented, but its actual impact on the light state depends on the application.

Usage

1. Initialize the LwM2M client with lwm2m_object_light_control_init, by passing a pointer to the LwM2M client data.
2. Now you can create instances of the Light Control object with lwm2m_object_light_control_instance_create. As part of the arguments, you can pass a callback that will be called when the light resources are updated (i.e. status, dimmer, color, app_type), as well as an user argument.

#define LIGHT_COLOR "FFFFFF"
#define LIGHT_APP_TYPE "LED 0"
 
// ... ///
 
void _light_cb(lwm2m_object_t *object, uint16_t instance_id, bool status, uint8_t dimmer,
               const char* color, const char* app_type, void *arg)
{
    (void)object;
    (void)instance_id;
    (void)arg;
 
    printf("%s is now %s, ", app_type, status? "ON":"OFF");
    printf("with color %s and intensity %d%%\n", color, dimmer);
}
 
// ... ///
 
lwm2m_object_t *light_control;
lwm2m_client_data_t client_data;
 
lwm2m_client_init(&client_data);
light_control = lwm2m_object_light_control_init(&client_data);
 
lwm2m_obj_light_control_args_t args = {
   .cb = _light_cb,
   .cb_arg = NULL,
   .color = LIGHT_COLOR,
   .color_len = sizeof(LIGHT_COLOR) - 1,
   .app_type = LIGHT_APP_TYPE,
   .app_type_len = sizeof(LIGHT_APP_TYPE) - 1
};
 
int result = lwm2m_object_light_control_instance_create(&args, 0);

1. You can update the status, dimmer, color and app_type of the light control instance with lwm2m_object_light_control_update_status, lwm2m_object_light_control_update_dimmer, lwm2m_object_light_control_update_color and lwm2m_object_light_control_update_app_type respectively. This will make sure to send notifications to servers that may be observing these resources.

lwm2m_object_light_control_update_status(0, true, false);
lwm2m_object_light_control_update_dimmer(0, 50, false);

Topics
	LwM2M Light Control object compile configurations

Files
file	light_control.h

Data Structures
struct	lwm2m_obj_light_control_args
	Arguments for the creation of a Light Control object instance. More...

Macros
#define	LWM2M_LIGHT_CONTROL_OBJECT_ID   3311
	Light Control object ID.

Typedefs
typedef void(*	lwm2m_obj_light_control_cb_t) (lwm2m_object_t *object, uint16_t instance_id, bool status, uint8_t dimmer, const char *color, const char *app_type, void *arg)
	Signature of the callback called when the light resources are updated.
typedef struct lwm2m_obj_light_control_args	lwm2m_obj_light_control_args_t
	Arguments for the creation of a Light Control object instance.

Functions
lwm2m_object_t *	lwm2m_object_light_control_init (lwm2m_client_data_t *client_data)
	Initialize the Light Control object.
int	lwm2m_object_light_control_instance_create (const lwm2m_obj_light_control_args_t *args, int32_t instance_id)
	Create a new Light Control instance and add it to the object list.
int	lwm2m_object_light_control_update_status (uint16_t instance_id, bool status, bool call_cb)
	Update the status of a light control instance.
int	lwm2m_object_light_control_update_dimmer (uint16_t instance_id, uint8_t dimmer, bool call_cb)
	Update the dimmer value of a light control instance.
int	lwm2m_object_light_control_update_color (uint16_t instance_id, const char *color, size_t len, bool call_cb)
	Update the color of a light control instance.
int	lwm2m_object_light_control_update_app_type (uint16_t instance_id, const char *app_type, size_t len, bool call_cb)
	Update the application type of a light control instance.

Light Control object resource's IDs.
#define	LWM2M_LIGHT_CONTROL_ON_OFF_ID   5850
	Light status resource ID.
#define	LWM2M_LIGHT_CONTROL_DIMMER_ID   5851
	Dimmer value resource ID.
#define	LWM2M_LIGHT_CONTROL_ON_TIME_ID   5852
	On Time resource ID.
#define	LWM2M_LIGHT_CONTROL_ACT_PWR_ID   5805
	Light active power resource ID.
#define	LWM2M_LIGHT_CONTROL_PWR_FACTOR_ID   5820
	Light power factor resource ID.
#define	LWM2M_LIGHT_CONTROL_COLOUR_ID   5706
	Light color resource ID.
#define	LWM2M_LIGHT_CONTROL_UNITS_ID   5701
	Units of the power sensing resource ID.
#define	LWM2M_LIGHT_CONTROL_APP_TYPE_ID   5750
	Light application type resource ID.

Macro Definition Documentation

LWM2M_LIGHT_CONTROL_ACT_PWR_ID

#define LWM2M_LIGHT_CONTROL_ACT_PWR_ID   5805

Light active power resource ID.

Definition at line 168 of file light_control.h.

LWM2M_LIGHT_CONTROL_APP_TYPE_ID

#define LWM2M_LIGHT_CONTROL_APP_TYPE_ID   5750

Light application type resource ID.

Definition at line 184 of file light_control.h.

LWM2M_LIGHT_CONTROL_COLOUR_ID

#define LWM2M_LIGHT_CONTROL_COLOUR_ID   5706

Light color resource ID.

Definition at line 176 of file light_control.h.

LWM2M_LIGHT_CONTROL_DIMMER_ID

#define LWM2M_LIGHT_CONTROL_DIMMER_ID   5851

Dimmer value resource ID.

Definition at line 160 of file light_control.h.

LWM2M_LIGHT_CONTROL_OBJECT_ID

#define LWM2M_LIGHT_CONTROL_OBJECT_ID   3311

Light Control object ID.

Definition at line 147 of file light_control.h.

LWM2M_LIGHT_CONTROL_ON_OFF_ID

#define LWM2M_LIGHT_CONTROL_ON_OFF_ID   5850

Light status resource ID.

Definition at line 156 of file light_control.h.

LWM2M_LIGHT_CONTROL_ON_TIME_ID

#define LWM2M_LIGHT_CONTROL_ON_TIME_ID   5852

On Time resource ID.

Definition at line 164 of file light_control.h.

LWM2M_LIGHT_CONTROL_PWR_FACTOR_ID

#define LWM2M_LIGHT_CONTROL_PWR_FACTOR_ID   5820

Light power factor resource ID.

Definition at line 172 of file light_control.h.

LWM2M_LIGHT_CONTROL_UNITS_ID

#define LWM2M_LIGHT_CONTROL_UNITS_ID   5701

Units of the power sensing resource ID.

Definition at line 180 of file light_control.h.

Typedef Documentation

lwm2m_obj_light_control_cb_t

typedef void(* lwm2m_obj_light_control_cb_t) (lwm2m_object_t *object, uint16_t instance_id, bool status, uint8_t dimmer, const char *color, const char *app_type, void *arg)

Signature of the callback called when the light resources are updated.

Parameters

[in]	object	Light Control object handle.
[in]	instance_id	ID of the instance where the resource changed.
[in]	status	Light status.
[in]	dimmer	Dimmer value.
[in]	color	Light color NULL-terminated string.
[in]	app_type	Light application type NULL-terminated string.
[in]	arg	Argument registered in lwm2m_object_light_control_instance_create.

Definition at line 199 of file light_control.h.

Function Documentation

lwm2m_object_light_control_init()

lwm2m_object_t * lwm2m_object_light_control_init

(

lwm2m_client_data_t *

client_data

)

Initialize the Light Control object.

Parameters

[in]

client_data

LwM2M client data.

Returns

Pointer to the Light Control object on success

lwm2m_object_light_control_instance_create()

int lwm2m_object_light_control_instance_create	(	const lwm2m_obj_light_control_args_t *	args,
		int32_t	instance_id )

Create a new Light Control instance and add it to the object list.

Parameters

[in]	args	Initialize structure with the parameter for the instance. May not be NULL.
[in]	instance_id	ID for the new instance. It must be between 0 and (UINT16_MAX - 1), if -1 the next available ID will be used.

Returns

0 on success

-EINVAL if an invalid instance_id is given

-ENOMEM if no memory is available to create a new instance

lwm2m_object_light_control_update_app_type()

int lwm2m_object_light_control_update_app_type	(	uint16_t	instance_id,
		const char *	app_type,
		size_t	len,
		bool	call_cb )

Update the application type of a light control instance.

Parameters

[in]	instance_id	ID of the instance to update.
[in]	app_type	New application type of the light.
[in]	len	Length of the app_type string.
[in]	call_cb	If true, the callback lwm2m_obj_light_control_args_t::cb will be called.

Returns

0 on success

-EINVAL if the instance does not exist

-ENOBUFS if the app_type string is too long

lwm2m_object_light_control_update_color()

int lwm2m_object_light_control_update_color	(	uint16_t	instance_id,
		const char *	color,
		size_t	len,
		bool	call_cb )

Update the color of a light control instance.

Parameters

[in]	instance_id	ID of the instance to update.
[in]	color	New color of the light.
[in]	len	Length of the color string.
[in]	call_cb	If true, the callback lwm2m_obj_light_control_args_t::cb will be called.

Returns

0 on success

-EINVAL if the instance does not exist

-ENOBUFS if the color string is too long

lwm2m_object_light_control_update_dimmer()

int lwm2m_object_light_control_update_dimmer	(	uint16_t	instance_id,
		uint8_t	dimmer,
		bool	call_cb )

Update the dimmer value of a light control instance.

Parameters

[in]	instance_id	ID of the instance to update.
[in]	dimmer	New dimmer value.
[in]	call_cb	If true, the callback lwm2m_obj_light_control_args_t::cb will be called.

Returns

0 on success

-EINVAL if the instance does not exist

lwm2m_object_light_control_update_status()

int lwm2m_object_light_control_update_status	(	uint16_t	instance_id,
		bool	status,
		bool	call_cb )

Update the status of a light control instance.

Parameters

[in]	instance_id	ID of the instance to update.
[in]	status	New status of the light.
[in]	call_cb	If true, the callback lwm2m_obj_light_control_args_t::cb will be called.

Returns

0 on success

-EINVAL if the instance does not exist