info-client.h File Reference

INFO for client. More...

#include <virgil/iot/protocols/snap/info/info-structs.h>
#include <virgil/iot/protocols/snap/snap-structs.h>
#include <virgil/iot/status_code/status_code.h>

Go to the source code of this file.

Data Structures
struct	vs_snap_info_client_service_t
	INFO client implementations. More...

Typedefs
typedef vs_status_e(*	vs_snap_info_wait_t) (uint32_t wait_ms, int *condition, int idle)
	Wait implementation. More...
typedef vs_status_e(*	vs_snap_info_stop_wait_t) (int *condition, int expect)
	Wait and stop callback. More...
typedef vs_status_e(*	vs_snap_info_start_notif_cb_t) (vs_snap_info_device_t *device)
	Start notification request. More...
typedef vs_status_e(*	vs_snap_info_general_cb_t) (vs_info_general_t *general_info)
	General device information request. More...
typedef vs_status_e(*	vs_snap_info_statistics_cb_t) (vs_info_statistics_t *statistics)
	Device statistics request. More...

Functions
const vs_snap_service_t *	vs_snap_info_client (vs_snap_info_client_service_t impl)
	INFO Client SNAP Service implementation. More...
vs_status_e	vs_snap_info_enum_devices (const vs_netif_t *netif, vs_snap_info_device_t *devices, size_t devices_max, size_t *devices_cnt, uint32_t wait_ms)
	Enumerate devices. More...
vs_status_e	vs_snap_info_set_polling (const vs_netif_t *netif, const vs_mac_addr_t *mac, uint32_t elements, bool enable, uint16_t period_seconds)
	Set pooling. More...

Detailed Description

INFO for client.

INFO service is used to provide information about current device state in the local network. Network in this case is limited by SNAP transport protocol.

In INFO meaning "Server" is any functional device. "Client" is the special device for statistic collection only. It can be any server PC or MCU device. Servers send their statistic information by startup. Also client can request periodical state sending by polling request.

Virgil IoT KIT provides client example as virgil-snapd application.

INFO Client usage

Before first INFO calls usage it is necessary to register INFO Client service :

const vs_snap_service_t *snap_info_client;     // INFO service
vs_snap_info_device_t devices[100];            // Devices list. Assuming 100 devices in the list is enough
const size_t devices_max = sizeof(devices) / sizeof(devices[0]);   // Maximum devices in the list
size_t devices_amount = 0;                     // Enumerates devices amount
uint32_t wait_ms = 3000;                       // Waiting 3 seconds for all devices enumerating
vs_mac_addr_t own_mac;                         // Own MAC address
uint16_t poll_period_sec = 1;                  // Send statistics each second
 
// Initialize own_mac
 
// Register INFO Client service
snap_info_client = vs_snap_info_client(_info_client_impl());
STATUS_CHECK(vs_snap_register_service(snap_info_client), "Cannot register INFO Сlient service");
 
// Enumerate devices
STATUS_CHECK(vs_snap_info_enum_devices(NULL, devices, devices_max, &devices_amount, wait_ms),
   "Unable to enumerate devices in the network");
 
// Request periodical state sending for all parameters
STATUS_CHECK(vs_snap_info_set_polling(NULL, &own_mac, VS_SNAP_INFO_GENERAL | VS_SNAP_INFO_STATISTICS, true,
   poll_period_sec), "Unable to request periodical polling sends");

own_mac is initialized by current device MAC address. It can be provided by vs_snap_mac_addr call.

vs_snap_info_client receives structure with notification implementations :

Note

All callbacks can be NULL.

vs_status_e
_device_start_impl(vs_snap_info_device_t *device) {
     // Process startup notification
 }
 
vs_status_e
_general_info_impl(vs_info_general_t *general_info) {
     // Process general device information
 }
 
vs_status_e
_statistics_impl(vs_info_statistics_t *statistics) {
     // Process device statistics
 }
 
vs_snap_info_client_service_t
_info_client_impl() {
     vs_snap_info_client_service_t impl;
     impl.device_start = _device_start_impl;
     impl.general_info = _general_info_impl;
     impl.statistics = _statistics_impl;
}

Polling is started by vs_snap_info_set_polling request with enable = true. enable = false removes specified statistic element specified by elements mask.

Typedef Documentation

vs_snap_info_general_cb_t

typedef vs_status_e(* vs_snap_info_general_cb_t) (vs_info_general_t *general_info)

General device information request.

This function is called by receiving general device information.

General device information polling is started by vs_snap_info_set_polling call when elements contains VS_SNAP_INFO_GENERAL bit.

Parameters

[in]

general_info

Device general information. Cannot be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_snap_info_start_notif_cb_t

typedef vs_status_e(* vs_snap_info_start_notif_cb_t) (vs_snap_info_device_t *device)

Start notification request.

This function is called by receiving startup notification from device.

Parameters

[in]

device

Device statical information. Cannot be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_snap_info_statistics_cb_t

typedef vs_status_e(* vs_snap_info_statistics_cb_t) (vs_info_statistics_t *statistics)

Device statistics request.

This function is called by receiving device statistics.

General device information polling is started by vs_snap_info_set_polling call when elements contains VS_SNAP_INFO_STATISTICS bit.

Parameters

[in]

statistics

Device statistics. Cannot be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_snap_info_stop_wait_t

typedef vs_status_e(* vs_snap_info_stop_wait_t) (int *condition, int expect)

Wait and stop callback.

Parameters

[in]	condition
[in]	expect

Returns

VS_CODE_OK in case of success or error code.

vs_snap_info_wait_t

typedef vs_status_e(* vs_snap_info_wait_t) (uint32_t wait_ms, int *condition, int idle)

Wait implementation.

Parameters

[in]	wait_ms
[in]	condition
[in]	idle

Returns

VS_CODE_OK in case of success or error code.

Function Documentation

vs_snap_info_client()

const vs_snap_service_t* vs_snap_info_client

(

vs_snap_info_client_service_t

impl

)

INFO Client SNAP Service implementation.

This call returns INFO client implementation. It must be called before any INFO call.

Parameters

[in]

impl

Snap Info Client functions implementation.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_info_enum_devices()

vs_status_e vs_snap_info_enum_devices	(	const vs_netif_t *	netif,
		vs_snap_info_device_t *	devices,
		size_t	devices_max,
		size_t *	devices_cnt,
		uint32_t	wait_ms
	)

Enumerate devices.

This call enumerates all devices present in the current network. It waits for wait_ms and returns collected information.

Parameters

[in]	netif	vs_netif_t SNAP service descriptor. If NULL, default one will be used.
[out]	devices	vs_snap_info_device_t Devices information list. Must not be NULL.
[in]	devices_max	Maximum devices amount. Must not be zero.
[out]	devices_cnt	Buffer to store devices amount. Must not be NULL.
[in]	wait_ms	Time to wait response.

Returns

VS_CODE_OK in case of success or error code.

vs_snap_info_set_polling()

vs_status_e vs_snap_info_set_polling	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		uint32_t	elements,
		bool	enable,
		uint16_t	period_seconds
	)

Set pooling.

This call enables or disables polling for elements masked in elements field that contains mask with vs_snap_info_element_mask_e fields.

Parameters

[in]	netif	vs_netif_t SNAP service descriptor. If NULL, default one will be used.
[in]	mac	vs_mac_addr_t MAC address. Must not be NULL.
[in]	elements	vs_snap_info_element_mask_e mask.
[out]	enable	Enable or disable elements to be sent.
[in]	period_seconds	Period in seconds for statistics sending

Returns

VS_CODE_OK in case of success or error code.