SenMLPack represents a single senml document that can be sent or received. More...

#include <senml_pack.h>

Inherited by SenMLPackTemplate< T >, SenMLPackTemplate< double >, and SenMLPackTemplate< int >.

Public Member Functions
	SenMLPack ()
	create a SenMLPack object.
	SenMLPack (const char *baseName)
	create a SenMLPack object.
	SenMLPack (const char *baseName, SenMLUnit baseUnit)
	create a SenMLPack object.
	SenMLPack (const char *baseName, SenMLUnit baseUnit, double baseTime)
	create a SenMLPack object.
	SenMLPack (PACK_ACTUATOR_SIGNATURE)
	create a SenMLPack object.
	SenMLPack (const char *baseName, PACK_ACTUATOR_SIGNATURE)
	create a SenMLPack object.
	SenMLPack (const char *baseName, SenMLUnit baseUnit, PACK_ACTUATOR_SIGNATURE)
	create a SenMLPack object.
	SenMLPack (const char *baseName, SenMLUnit baseUnit, double baseTime, PACK_ACTUATOR_SIGNATURE)
	create a SenMLPack object.
	~SenMLPack ()
	destroys the SenMLPack object.
void	toJson (Stream *dest, SenMLStreamMethod format=SENML_RAW)
	render the content of the current object to json data (string).
void	toJson (char *dest, int length, SenMLStreamMethod format=SENML_RAW)
	render the content of the current object to json data (string).
int	toCbor (Stream *dest, SenMLStreamMethod format=SENML_RAW)
	render the content of the current object to cbor data (binary).
int	toCbor (char *dest, int length, SenMLStreamMethod format=SENML_RAW)
	render the content of the current object to cbor data (binary).
void	fromJson (Stream *source, SenMLStreamMethod format=SENML_RAW)
	read and parse a senml json string from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.
void	fromJson (const char *source)
	parse a senml json string from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.
void	fromCbor (Stream *source, SenMLStreamMethod format=SENML_RAW)
	read and parse senml cbor from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.
void	fromCbor (char *source, int length, SenMLStreamMethod format)
	parse senml cbor from the specified memory and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.
void	setBaseName (const char *name)
	assign a basename to the SenMLPack object.
const char *	getBaseName ()
	Get the base name.
void	setBaseUnit (SenMLUnit unit)
	Set the base unit that will be used as the default unit for all records that don't define their own unit.
SenMLUnit	getBaseUnit ()
	Get the base unit.
void	setBaseTime (double time)
	Set the base time.
double	getBaseTime ()
	Get the base time.
bool	add (SenMLBase *item)
	Adds the specified SenML object to the document.
bool	clear ()
	Clear out the document and remove all the children.
SenMLBase *	getFirst ()
	get the first recrod of in this pack element.
virtual void	fieldsToJson ()
	renders all the fields to json, without the starting and ending brackets.
virtual int	fieldsToCbor ()
	renders all the fields to cbor format.
SenMLBase *	getNext ()
	get the next item in the list.
SenMLBase *	getRoot ()
	Get the root object of this list.
Friends
class	SenMLJsonListener
class	SenMLCborParser
class	SenMLBase

Detailed Description

SenMLPack represents a single senml document that can be sent or received.

A senmlPack object has SenMLRecords and/or other SenMLPack objects as children. These represent the data that the object contains. A SenMLRecord represents a single value, while child SenMLPacks represent data of other devices. When a SenMLPack contains other SenMLPack objects, the root object represents a gateway.

A SenMLPack object is able to render and parse the data to/from a json string or to/from binary CBOR data. Both rendering and parsing can be done either directly from a stream (like an UART connected to a modem), or from a memory buffer. Rendering to and parsing from a stream is useful for devices that have extreme low memory available. Almost no buffers are used in this case. Error handling is limited in this case though. The parser and generator are able to render in the native format (strings for json, binary data for cbor) and as a hex string. This is especially useful when directly working on a stream: some modems (ex lora) accept instructions with data in HEX format.

example:

 #include <kpn_senml.h>
 
 SenMLPack doc("device_name");
 
 void setup(){
     Serial.begin(57600);
     senMLSetLogger(&Serial);
     delay(1000);
     Serial.println("start");
 }

 void loop(){
     int val = 10;                                   //just give it some value
     SenMLFloatRecord rec("temp", SENML_UNIT_DEGREES_CELSIUS, val);
     doc.add(&rec);                      
     doc.toJson(&Serial);                            //as text
     Serial.println();
     doc.toJson(&Serial, SENML_HEX);                 //in hex format (often used in communication with lora modems)
     Serial.println();
     delay(1000);
 }

Definition at line 75 of file senml_pack.h.

Constructor & Destructor Documentation

SenMLPack ( )

create a SenMLPack object.

Definition at line 85 of file senml_pack.h.

SenMLPack ( const char * baseName )

create a SenMLPack object.

Parameters:

baseName the string that will be prepended to all records in this pack. Is used to represent the name of the device.

Definition at line 94 of file senml_pack.h.

SenMLPack	(	const char *	baseName,
		SenMLUnit	baseUnit
	)

create a SenMLPack object.

Parameters:

baseName	the string that will be prepended to all records in this pack. Is used to represent the name of the device.
baseUnit	the unit name that will be used by default if the record doesnt not define one.

Definition at line 106 of file senml_pack.h.

SenMLPack	(	const char *	baseName,
		SenMLUnit	baseUnit,
		double	baseTime
	)

create a SenMLPack object.

Parameters:

baseName	the string that will be prepended to all records in this pack. Is used to represent the name of the device.
baseUnit	the unit name that will be used by default if the record doesnt not define one.
baseTime	the time that will be added to each record. When specified, each record that does not specify a time, will receive this time. When the record does have a time, the baseTime of the pack is added to it, so the time of the record becomes relative to that of the pack.

Definition at line 122 of file senml_pack.h.

SenMLPack ( PACK_ACTUATOR_SIGNATURE )

create a SenMLPack object.

Parameters:

callback a function that will be called while parsing incomming data, when no record can be found that matches any of the defined ones in the object. The parameters of the callback must be: const char* packName the name of the pack that the record belongs to. The data is for a child SenMLPack when this field is different then the name of the root pack. const char* recordName the name of the record const void* value a pointer to the memory blob that contains the actual value. int size the size of the memory blobl SenMLDataType dataType: defines how to interprete the memory blob (ex: pointer to integer,..)

Definition at line 140 of file senml_pack.h.

SenMLPack	(	const char *	baseName,
		PACK_ACTUATOR_SIGNATURE
	)

create a SenMLPack object.

Parameters:

baseName the string that will be prepended to all records in this pack. Is used to represent the name of the device.

callback a function that will be called while parsing incomming data, when no record can be found that matches any of the defined ones in the object. The parameters of the callback must be: const char* packName the name of the pack that the record belongs to. The data is for a child SenMLPack when this field is different then the name of the root pack. const char* recordName the name of the record const void* value a pointer to the memory blob that contains the actual value. int size the size of the memory blobl SenMLDataType dataType: defines how to interprete the memory blob (ex: pointer to integer,..)

Definition at line 161 of file senml_pack.h.

SenMLPack	(	const char *	baseName,
		SenMLUnit	baseUnit,
		PACK_ACTUATOR_SIGNATURE
	)

create a SenMLPack object.

Parameters:

baseName	the string that will be prepended to all records in this pack. Is used to represent the name of the device.
baseUnit	the unit name that will be used by default if the record doesnt not define one.
callback	a function that will be called while parsing incomming data, when no record can be found that matches any of the defined ones in the object. The parameters of the callback must be: const char* packName the name of the pack that the record belongs to. The data is for a child SenMLPack when this field is different then the name of the root pack. const char* recordName the name of the record const void* value a pointer to the memory blob that contains the actual value. int size the size of the memory blobl SenMLDataType dataType: defines how to interprete the memory blob (ex: pointer to integer,..)

Definition at line 184 of file senml_pack.h.

SenMLPack	(	const char *	baseName,
		SenMLUnit	baseUnit,
		double	baseTime,
		PACK_ACTUATOR_SIGNATURE
	)

create a SenMLPack object.

Parameters:

baseName	the string that will be prepended to all records in this pack. Is used to represent the name of the device.
baseUnit	the unit name that will be used by default if the record doesnt not define one.
baseTime	the time that will be added to each record. When specified, each record that does not specify a time, will receive this time. When the record does have a time, the baseTime of the pack is added to it, so the time of the record becomes relative to that of the pack.
callback	a function that will be called while parsing incomming data, when no record can be found that matches any of the defined ones in the object. The parameters of the callback must be: const char* packName the name of the pack that the record belongs to. The data is for a child SenMLPack when this field is different then the name of the root pack. const char* recordName the name of the record const void* value a pointer to the memory blob that contains the actual value. int size the size of the memory blobl SenMLDataType dataType: defines how to interprete the memory blob (ex: pointer to integer,..)

Definition at line 211 of file senml_pack.h.

~SenMLPack ( )

destroys the SenMLPack object.

Definition at line 220 of file senml_pack.h.

Member Function Documentation

bool add ( SenMLBase * item )

Adds the specified SenML object to the document.

The item will be appended to the end of the linked list. The item being added, can be a regular SenMLRecord or another SenMLPack object if you want to send data for multiple devices in 1 SenML message. Check the result of the function to see if the operation was successful or not. Possible reasons for failure:

if the item being added is already part of a document.
Parameters:

item a pointer to a SenMlRecord or SenMLPack that needs to be added to the document.

Returns:
true upon success, otherwise false.

Definition at line 64 of file senml_pack.cpp.

bool clear ( )

Clear out the document and remove all the children.

Children aren't destroyed, this is up to the developer.

Returns:: true (at the moment, the function does not yet return false as it doesn't detect any errors)

Definition at line 84 of file senml_pack.cpp.

int fieldsToCbor ( ) [virtual]

renders all the fields to cbor format.

renders all the fields of the object without the length info at the beginning note: this is public so that custom implementations for the record object can use other objects internally and render to json using this function (ex: coordinatesRecord using 3 floatRecrods for lat, lon & alt.

Returns:: : The number of bytes that were written.

Implements SenMLBase.

Reimplemented in SenMLDoublePack, and SenMLIntPack.

Definition at line 316 of file senml_pack.cpp.

void fieldsToJson ( ) [virtual]

renders all the fields to json, without the starting and ending brackets.

Inheriters can extend this function if they want to add extra fields to the json output note: this is public so that custom implementations for the record object can use other objects internally and render to json using this function (ex: coordinatesRecord using 3 floatRecrods for lat, lon & alt.

Returns:: : None

Implements SenMLBase.

Reimplemented in SenMLDoublePack, and SenMLIntPack.

Definition at line 185 of file senml_pack.cpp.

void fromCbor	(	char *	source,
		int	length,
		SenMLStreamMethod	format
	)

parse senml cbor from the specified memory and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.

This method takes a memory blob as input. The data must be fully defined.

Parameters:

source	the source data to use as input.
length	the length of the source data.
format	determins how the data will be read (ex: as normal binary or in HEX format). See SenMLStreamMethod for possible methods.

Returns:: none

Definition at line 153 of file senml_pack.cpp.

void fromCbor	(	Stream *	source,
		SenMLStreamMethod	format = `SENML_RAW`
	)

read and parse senml cbor from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.

This method is ideal for devices with very littel ram memory. It will block on most decices if there is no more input to be read from the stream and the end of the cbor structure is not yet reached. Note: on mbed systems, the blocking nature is not garanteed. Instead, if no more data is available before the end is reached, parsing will fail.

Parameters:

source	the source stream to read the data from.
format	determins how the data will be read (ex: as normal binary or in HEX format). See SenMLStreamMethod for possible methods.

Returns:: none

Definition at line 147 of file senml_pack.cpp.

void fromJson	(	Stream *	source,
		SenMLStreamMethod	format = `SENML_RAW`
	)

read and parse a senml json string from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.

This method is ideal for devices with very littel ram memory. It will block on most devices if there is no more input to be read from the stream and the end of the json structure is not yet reached. Note: on mbed systems, the blocking nature is not garanteed. Instead, if no more data is available before the end is reached, parsing will fail.

Parameters:

source	the source stream to read the data from.
format	determins how the data will be read (ex: as normal text or in HEX format). See SenMLStreamMethod for possible methods.

Returns:: none

Definition at line 102 of file senml_pack.cpp.

void fromJson ( const char * source )

parse a senml json string from the specified source and, for each registered actuator, call the appropriate event on the actuator itself, for others, the callback function PACK_ACTUATOR_SIGNATURE will be called, if present.

This method takes a string stored in memory as input. The json must be fully defined. It is up to the caller to transform it to a regular text string, if needed (ex: lora devices might send it in hex format).

Parameters:

source the source string to use as input. This must be null terminated.

Returns:: none

Definition at line 135 of file senml_pack.cpp.

const char * getBaseName ( )

Get the base name.

see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info.

Returns:: the name of the device as an immutable string.

Definition at line 32 of file senml_pack.cpp.

double getBaseTime ( )

Get the base time.

see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info.

Returns:: a double value that is used as the default unit for records that don't define a unit of their own. if no base time is set, NaN will be returned.

Definition at line 361 of file senml_pack.h.

SenMLUnit getBaseUnit ( )

Get the base unit.

see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info.

Returns:: a SenMLUnit enum value that is used as the default unit for records that don't define a unit of their own.

Definition at line 346 of file senml_pack.h.

SenMLBase* getFirst ( )

get the first recrod of in this pack element.

Returns:: null when this object is empty (has no children), otherwise, the first item (SenMLRecord or SenMLPack) of the list.

Definition at line 385 of file senml_pack.h.

SenMLBase* getNext ( ) [inherited]

get the next item in the list.

Returns:: : a pointer to the next SenMLBase object in the list or NULL when at the end of the list.

Definition at line 42 of file senml_base.h.

SenMLBase * getRoot ( ) [inherited]

Get the root object of this list.

Usually, this is a SenMLPack object. The root object is defined as the first item in the list.

Returns:: : a pointer to the first SenMLBase object in the list or NULL when there is none.

Definition at line 53 of file senml_base.cpp.

void setBaseName ( const char * name )

assign a basename to the SenMLPack object.

This represents the name of the device. see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info. Every SenMLPack object must have a basename. This field will always be rendered in the output, even if the string is empty.

Parameters:

name	an immutable string that will be used to represent the name of the device. An internal copy of the value will be made.

Returns:: none

Definition at line 27 of file senml_pack.cpp.

void setBaseTime ( double time )

Set the base time.

see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info.

Parameters:

time	the value to use as base time. set bt to NaN if the field should not be included in the output.

Returns:: none

Definition at line 43 of file senml_pack.cpp.

void setBaseUnit ( SenMLUnit unit )

Set the base unit that will be used as the default unit for all records that don't define their own unit.

see the spec on [base fields](https://tools.ietf.org/html/draft-ietf-core-senml-13#section-4.1) for more info. Set to SENML_UNIT_NONE for ommiting the base unit from the output (default).

Parameters:

unit	the unit to use as default. See SenMLUnit for all supported unit names.

Returns:: none

Definition at line 37 of file senml_pack.cpp.

int toCbor	(	Stream *	dest,
		SenMLStreamMethod	format = `SENML_RAW`
	)

render the content of the current object to cbor data (binary).

This function is ideal for devices with low memory usage but offers less control over the rendering process.

Parameters:

dest	the destination stream to where the data will be rendered without buffering it in memory
format	determins how the data will be rendered. See SenMLStreamMethod for possible methods.

Returns:: nr of bytes that were rendered

Definition at line 246 of file senml_pack.cpp.

int toCbor	(	char *	dest,
		int	length,
		SenMLStreamMethod	format = `SENML_RAW`
	)

render the content of the current object to cbor data (binary).

This function renders the data to a memory buffer. If the buffer is full before the entire object is rendered, an error will be written to the debug stream.

Parameters:

dest	a memory buffer to which the data will be rendred.
length	the length of the memory buffer.
format	determins how the data will be rendered. See SenMLStreamMethod for possible methods.

Returns:: nr of bytes that were rendered

Definition at line 256 of file senml_pack.cpp.

void toJson	(	char *	dest,
		int	length,
		SenMLStreamMethod	format = `SENML_RAW`
	)

render the content of the current object to json data (string).

This function renders the data to a memory buffer. If the buffer is full before the entire object is rendered, an error will be written to the debug stream.

Parameters:

dest	a memory buffer to which the data will be rendred.
length	the length of the memory buffer.
format	determins how the data will be rendered. See SenMLStreamMethod for possible methods.

Returns:: none

Definition at line 168 of file senml_pack.cpp.

void toJson	(	Stream *	dest,
		SenMLStreamMethod	format = `SENML_RAW`
	)

render the content of the current object to json data (string).

This function is ideal for devices with low memory usage but offers less control over the rendering process.

Parameters:

dest	the destination stream to where the data will be rendered without buffering it in memory
format	determins how the data will be rendered. See SenMLStreamMethod for possible methods.

Returns:: none

Definition at line 160 of file senml_pack.cpp.

Type:	Library
Created:	27 May 2018
Imports:	4
Forks:	0
Commits:	3
Dependents:	0
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

SenMLPack Class Reference

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

SenMLPack Class Reference

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning