Detailed Description

Example app using the Beacon Vendor Specific IE Filter API.

Note: It is assumed that you have followed the steps in the Getting Started guide and are therefore familiar with how to build, flash, and monitor an application using the MM-IoT-SDK framework.; We will only briefly touch on the AP side of this feature as it is out of scope for this documentation.

Beacon Stuffing Overview

In a HaLow network the AP will send beacons out at a set interval. These can either be long beacons or short beacons. Currently we can add additional Information Elements (IEs) to the long beacons.

Generally speaking a long beacon looks something like the following.

+-------------------+------+------+       +------+
| S1G Beacon Header | IE_1 | IE_2 | ..... | IE_n |
+-------------------+------+------+       +------+
                    ^                            ^
                    |-------------IEs------------|

Beacon stuffing allows Vendor Specific IEs to be placed into the long beacons. This API allows you to register a callback with a reference to the IEs when certain Vendor Specific IEs are detected in the beacon.

A Vendor Specific IE has the following structure

|------------|--------|--------------|---------------------------|
| Element ID | Length |      OUI     |  Vendor specific content  |
|------------|--------|--------------|---------------------------|
       1         1            3                variable

Note: Note that the API current only supports filtering on a 24-bit Organizational Unique Identifier (OUI).

Application Overview

This application connects and then installs one OUI to filter on. It will then log how many times it sees the Vendor Specific IE and the most recent data received.

Additionally, if the length of the vendor specific content is greater than or equal to RGB_DATA_LENGTH_BYTES this application will treat it as intensity levels for the red, green and blue LEDs. These will be set in the callback using mmhal_set_led().

To add a Vendor Specific IE using a Morse Micro AP the following command can be used.

morse_cli vendor_ie -a 4D4D42FF00FF -b

This will add a Vendor Specific IE with

OUI = 0x4D4D42
Vendor Specific Content = 0xFF00FF

To clear the Vendor Specific IEs.

morse_cli vendor_ie -c -b

Note: A beacon may contain multiple Vendor IEs with the same OUI. The handling of these is application specific. In this example application, only the first matching Vendor IE is processed and subsequent Vendor IEs with the same OUI, if present, are ignored.

Configuration

See Application helper routines for Wireless LAN interface for details of WLAN and IP stack configuration. Additional configuration options for this application can be found in the config.hjson file.

Definition in file beacon_stuffing.c.

#include <string.h>
#include <endian.h>
#include "mmhal.h"
#include "mmosal.h"
#include "mmwlan.h"
#include "mmconfig.h"
#include "mmutils.h"
#include "mm_app_common.h"

Include dependency graph for beacon_stuffing.c:

Go to the source code of this file.

Data Structures
struct	beacon_vendor_ie_stat
	Structure to store some basic statistics for the beacon Vendor Specific IE reception. More...

Macros
#define	DEFAULT_OUI {0x4D, 0x4D, 0x42};
	OUI to look for in the Vendor Specific IE. More...

#define	DEFAULT_LOG_LEN_BYTES 30
	Length of the data to print when logging the stat struct. More...

#define	DEFAULT_STATS_UPDATE_PERIOD_MS 1000
	How often the contents for the stat struct is logged. More...

#define	FILTER_INDEX 0
	Filter index to install the OUI. More...

#define	RGB_DATA_LENGTH_BYTES 3
	Length of data required for updating the LED state. More...

Functions
static void	beacon_vendor_ie_callback (const uint8_t ies, uint32_t ies_len, void arg)
	Callback function that gets executed every time a beacon containing a matching Vendor Specific IE is received. More...

static void	beacon_vendor_ie_stat_log (struct beacon_vendor_ie_stat *stat, uint32_t max_data_log_len)
	Print the contents of the given stat struct using `printf()`. More...

void	app_init (void)
	Main entry point to the application. More...

Variables
struct mmwlan_beacon_vendor_ie_filter	filter
	Filter structure used when calling mmwlan_update_beacon_vendor_ie_filter(). More...

Macro Definition Documentation

◆ DEFAULT_LOG_LEN_BYTES

#define DEFAULT_LOG_LEN_BYTES 30

Length of the data to print when logging the stat struct.

If the data is longer than this it will be truncated.

Definition at line 98 of file beacon_stuffing.c.

◆ DEFAULT_OUI

#define DEFAULT_OUI {0x4D, 0x4D, 0x42};

OUI to look for in the Vendor Specific IE.

Note: This is a made up OUI for the purposes of this application. Your final application will likely need an OUI specific to your company.

Definition at line 95 of file beacon_stuffing.c.

◆ DEFAULT_STATS_UPDATE_PERIOD_MS

#define DEFAULT_STATS_UPDATE_PERIOD_MS 1000

How often the contents for the stat struct is logged.

Definition at line 100 of file beacon_stuffing.c.

◆ FILTER_INDEX

#define FILTER_INDEX 0

Filter index to install the OUI.

Definition at line 104 of file beacon_stuffing.c.

◆ RGB_DATA_LENGTH_BYTES

#define RGB_DATA_LENGTH_BYTES 3

Length of data required for updating the LED state.

Definition at line 106 of file beacon_stuffing.c.

Function Documentation

◆ app_init()

void app_init ( void )

Main entry point to the application.

This will be invoked in a thread once operating system and hardware initialization has completed. It may return, but it does not have to.

Definition at line 214 of file beacon_stuffing.c.

◆ beacon_vendor_ie_callback()

static void beacon_vendor_ie_callback	(	const uint8_t *	ies,
		uint32_t	ies_len,
		void *	arg
	)

static

Callback function that gets executed every time a beacon containing a matching Vendor Specific IE is received.

Current implementation will log the stats for the filter specified and update the state of the LEDs on the board using mmhal_set_led(). The LED update only occurs if there is at least RGB_DATA_LENGTH_BYTES worth of data after the OUI.

Parameters

ies	Reference to the list of information elements (little endian order) present in the beacon that matched the filter.
ies_len	Length of the IE list in octets.
arg	Reference to the opaque argument provided with the filter.

Definition at line 136 of file beacon_stuffing.c.

◆ beacon_vendor_ie_stat_log()

static void beacon_vendor_ie_stat_log	(	struct beacon_vendor_ie_stat *	stat,
		uint32_t	max_data_log_len
	)

static

Print the contents of the given stat struct using printf().

Parameters

stat	Reference to the stat to print.
max_data_log_len	Maximum length in bytes to print for the data content in the stat struct.

Definition at line 191 of file beacon_stuffing.c.

Variable Documentation

◆ filter

struct mmwlan_beacon_vendor_ie_filter filter

Filter structure used when calling mmwlan_update_beacon_vendor_ie_filter().

We declare it here to ensure that the memory is always valid and not used for anything else.

Definition at line 110 of file beacon_stuffing.c.