oc_knx.h File Reference

implementation of /.well-known/knx and /k resources More...

#include <stddef.h>
#include "oc_api.h"

Go to the source code of this file.

Data Structures
struct	oc_group_object_notification_t
	Group Object Notification (s-mode messages) Can be used for receiving messages or sending messages. More...
struct	oc_pase_t
	Pase Resource Object. More...

Typedefs
typedef struct oc_group_object_notification_t	oc_group_object_notification_t
	Group Object Notification (s-mode messages) Can be used for receiving messages or sending messages. More...
typedef void(*	oc_lsm_change_cb_t) (size_t device, oc_lsm_state_t lsm_state, void *data)
	Callback invoked by the stack to inform the change of the lsm. More...
typedef enum oc_lsm_state	oc_lsm_state_t
	LSM state machine values. More...
typedef struct oc_pase_t	oc_pase_t
	Pase Resource Object. More...

Enumerations
enum	oc_lsm_event_t { LSM_E_NOP = 0 , LSM_E_STARTLOADING , LSM_E_LOADCOMPLETE = 2 , LSM_E_UNLOAD = 4 }
	LSM event values. More...
enum	oc_lsm_state {   LSM_S_UNLOADED = 0 , LSM_S_LOADED = 1 , LSM_S_LOADING = 2 , LSM_S_UNLOADING = 4 ,   LSM_S_LOADCOMPLETING = 5 }
	LSM state machine values. More...

Functions
int	oc_a_lsm_set_state (size_t device_index, oc_lsm_event_t new_state)
	retrieve the current lsm state More...
oc_lsm_state_t	oc_a_lsm_state (size_t device_index)
	retrieve the current lsm state More...
const char *	oc_core_get_lsm_event_as_string (oc_lsm_event_t lsm_e)
	convert the load state machine (lsm) event to string More...
const char *	oc_core_get_lsm_state_as_string (oc_lsm_state_t lsm_s)
	convert the load state machine (lsm) state to string More...
void	oc_create_knx_resources (size_t device)
	Creation of the KNX device resources. More...
bool	oc_is_device_in_runtime (size_t device_index)
	checks if the device is in "run-time" mode run-time is: More...
void	oc_knx_dump_fingerprint ()
	dump the fingerprint value to storage More...
void	oc_knx_increase_fingerprint ()
	increase the finger print value More...
int	oc_knx_knx_ignore_smessage_from_self (bool ignore)
	runtime switch to ignore s-mode messages send by ourselves. More...
void	oc_knx_load_fingerprint ()
	load the fingerprint value from storage More...
void	oc_knx_load_state (size_t device_index)
	load the state of the device from persistent storage load data for: More...
void	oc_knx_set_fingerprint (uint64_t fingerprint)
	sets the fingerprint value (of the loaded materials) More...
void	oc_knx_set_idevid (const char *idevid, int length)
	sets the idevid More...
void	oc_knx_set_ldevid (char *ldevid, int len)
	sets the ldevid More...
int	oc_reset_device (size_t device_index, int reset_value)
	reset the device the reset value according to the specification: More...
bool	oc_s_mode_notification_to_json (char *buffer, size_t buffer_size, oc_group_object_notification_t notification)
void	oc_set_lsm_change_cb (oc_lsm_change_cb_t cb, void *data)
	Set the load state machine change callback. More...

Detailed Description

implementation of /.well-known/knx and /k resources

Definition in file oc_knx.h.

Typedef Documentation

oc_group_object_notification_t

typedef struct oc_group_object_notification_t oc_group_object_notification_t

Group Object Notification (s-mode messages) Can be used for receiving messages or sending messages.

generic structures:

{ 5: { 6: "st value" , 7: "ga value", 1: "value" } }
 
{ 4: "sia", 5: { 6: "st", 7: "ga", 1: "value" } }

Key translation

Json Key	Integer Value	type
value	1	object
sia	4	uint32_t
s	5	object
st	6	string
ga	7	uint32_t

oc_lsm_change_cb_t

typedef void(* oc_lsm_change_cb_t) (size_t device, oc_lsm_state_t lsm_state, void *data)

Callback invoked by the stack to inform the change of the lsm.

Parameters

[in]	device	the device index
[out]	lsm_state	the new state of the lsm
[in]	data	the user supplied data

Definition at line 164 of file oc_knx.h.

oc_lsm_state_t

typedef enum oc_lsm_state oc_lsm_state_t

LSM state machine values.

oc_pase_t

typedef struct oc_pase_t oc_pase_t

Pase Resource Object.

Example Json:

{ "rnd": x}
{ "pa": x}
{ "pb": x}
{ "ca": x}
{ "pbkdf2" : { "salt" : "xxxx", "it" : 5}}}

Key translation

Json Key	Integer Value	type
salt	5	byte string
pa	10	byte string
pb	11	byte string
pbkdf2	12	map
cb	13	byte string
ca	14	byte string
rnd	15	byte string
it	16	unsigned

note no storage needed for map

Enumeration Type Documentation

oc_lsm_event_t

enum oc_lsm_event_t

LSM event values.

Enumerator
LSM_E_NOP	(0) No operation
LSM_E_STARTLOADING	(1) Request to start the loading of the loadable part
LSM_E_LOADCOMPLETE	(2) cmd loading complete, state will be LOADED
LSM_E_UNLOAD	(4) cmd unload: state will be UNLOADED

Definition at line 113 of file oc_knx.h.

             {
  LSM_E_NOP = 0, 
  LSM_E_STARTLOADING =
    1, 
  LSM_E_LOADCOMPLETE = 2, 
  LSM_E_UNLOAD = 4        
} oc_lsm_event_t;

oc_lsm_state

enum oc_lsm_state

LSM state machine values.

Enumerator
LSM_S_UNLOADED	(0) state is unloaded, e.g. ready for loading
LSM_S_LOADED	(1) state is LOADED, e.g. normal operation
LSM_S_LOADING	(2) state loading.
LSM_S_UNLOADING	(4) state unloading loading.
LSM_S_LOADCOMPLETING	(5) cmd unload: state will be UNLOADED

Definition at line 101 of file oc_knx.h.

                          {
  LSM_S_UNLOADED = 0,      
  LSM_S_LOADED = 1,        
  LSM_S_LOADING = 2,       
  LSM_S_UNLOADING = 4,     
  LSM_S_LOADCOMPLETING = 5 
} oc_lsm_state_t;

Function Documentation

oc_a_lsm_set_state()

int oc_a_lsm_set_state	(	size_t	device_index,
		oc_lsm_event_t	new_state
	)

retrieve the current lsm state

Parameters

device_index	index of the device to which the resource is to be created
new_state	the new lsm_state

Returns

0 == success

oc_a_lsm_state()

oc_lsm_state_t oc_a_lsm_state

(

size_t

device_index

)

retrieve the current lsm state

Parameters

device_index

index of the device to which the resource is to be created

Returns

the lsm state

oc_core_get_lsm_event_as_string()

const char* oc_core_get_lsm_event_as_string

(

oc_lsm_event_t

lsm_e

)

convert the load state machine (lsm) event to string

Parameters

lsm_e

the event

Returns

const char* The state as string

oc_core_get_lsm_state_as_string()

const char* oc_core_get_lsm_state_as_string

(

oc_lsm_state_t

lsm_s

)

convert the load state machine (lsm) state to string

Parameters

lsm_s

the state

Returns

const char* The state as string

oc_create_knx_resources()

void oc_create_knx_resources

(

size_t

device

)

Creation of the KNX device resources.

creates and handles the following resources:

• /a/lsm
• /k
• /.well-known/knx
• /.well-known/knx/osn
• /.well-known/knx/f (fingerprint)
• /.well-known/knx/ldevid (optional)
• /.well-known/knx/idevid (optional)
• /.well-known/knx/spake

Parameters

device

index of the device to which the resource is to be created

oc_is_device_in_runtime()

bool oc_is_device_in_runtime

(

size_t

device_index

)

checks if the device is in "run-time" mode run-time is:

• ia initialized (e.g. larger than 0)
• iid initialized (e.g. larger than 0)
• load state machine (lsm) == loaded

Parameters

device_index

The device index.

Returns

true in runtime

false not in run time

oc_knx_dump_fingerprint()

void oc_knx_dump_fingerprint

(

)

dump the fingerprint value to storage

oc_knx_increase_fingerprint()

void oc_knx_increase_fingerprint

(

)

increase the finger print value

oc_knx_knx_ignore_smessage_from_self()

int oc_knx_knx_ignore_smessage_from_self

(

bool

ignore

)

runtime switch to ignore s-mode messages send by ourselves.

The /k resource handles all incoming s-mode messages. This switch can be used to ignore s-mode messages that are send by ourselves.

note for the sniffer, all messages must be handled/reported. note for a Classic to IoT gateway the self send messages must be ignored

Parameters

ignore

true: ignore, false handle message

oc_knx_load_fingerprint()

void oc_knx_load_fingerprint

(

)

load the fingerprint value from storage

oc_knx_load_state()

void oc_knx_load_state

(

size_t

device_index

)

load the state of the device from persistent storage load data for:

• load state machine (lsm)

Parameters

device_index

the device index to load the data for

oc_knx_set_fingerprint()

void oc_knx_set_fingerprint

(

uint64_t

fingerprint

)

sets the fingerprint value (of the loaded materials)

Parameters

fingerprint

The fingerprint value

oc_knx_set_idevid()

void oc_knx_set_idevid	(	const char *	idevid,
		int	length
	)

sets the idevid

Parameters

idevid	the idevid certificate
length	the length of the certificate

oc_knx_set_ldevid()

void oc_knx_set_ldevid	(	char *	ldevid,
		int	len
	)

sets the ldevid

Parameters

ldevid	the ldevid certificate
len	the length of the certificate

oc_reset_device()

int oc_reset_device	(	size_t	device_index,
		int	reset_value
	)

reset the device the reset value according to the specification:

• reset = 2 (Factory Reset) :
  • individual address (ia)
  • host name (hname)
  • Installation ID (iid)
  • programming mode (pm)
  • device address (da)
  • sub address (sa)
  • group object table
  • recipient object table
  • publisher object table
• reset = 3 (reset ia) :
  • individual address (ia)
• reset = 7 (Factory Reset without IA):
  • group object table
  • recipient object table
  • publisher object table

See also

oc_knx_device_storage_reset

Parameters

device_index	the device index
reset_value	the reset value

Returns

int 0== success

oc_set_lsm_change_cb()

void oc_set_lsm_change_cb	(	oc_lsm_change_cb_t	cb,
		void *	data
	)

Set the load state machine change callback.

The callback is called by the stack when lsm is changed

Note

oc_set_hostname_cb() must be called before oc_main_init().

Parameters

[in]	cb	oc_hostname_cb_t function pointer to be called
[in]	data	context pointer that is passed to the oc_restart_cb_t the pointer must be a valid pointer till after oc_main_init() call completes.