MAC unified API for PicoWAN and LoRaWAN network access. More...

#include <stdint.h>

Data Structures
struct	mac_tx_info_t
	MAC transmit information. More...

struct	mac_rx_info_t
	MAC receive information. More...

struct	mac_network_info_t
	MAC network state information. More...

struct	mac_message_callbacks_t
	MAC events structure. Used to notify upper layers after each MAC events done. More...

struct	mac_battery_callback_t

struct	mac_flash_callback_t

Macros
#define	MAC_PORT_MAC_COMMAND 0

#define	MAC_PORT_FIRST_APP 1

Enumerations
enum	mac_type_t { UNDEF_MAC = -1, PICOMAC = 0, LORAMAC = 1 }

enum	downlink_mode_t { DL_DISABLED = 0, DL_ENABLED = 1 }

enum	ack_status { UNDEF_ACK, NO_ACK, ACK }

enum	device_class_t { CLASS_A, CLASS_B, CLASS_C }

enum	mac_state_t { MAC_STATE_IDLE = 0, MAC_STATE_SEARCHING_NETWORK = 1, MAC_STATE_SENDING_DATA = 2, MAC_STATE_WAITING_ACK = 3, MAC_STATE_WAITING_RETRY = 4, MAC_STATE_WAITING_DATA = 5 }

enum	mac_info_status_t { MAC_INFO_STATUS_DUTY_CYCLE_LIMITATION = -8, MAC_INFO_STATUS_DOWNLINK_DECODING_ERROR = -7, MAC_INFO_STATUS_DOWNLINK_TIMEOUT = -6, MAC_INFO_STATUS_RX_ERROR = -5, MAC_INFO_STATUS_TX_MAX_MSG_SIZE_EXCEEDED = -4, MAC_INFO_STATUS_MIC_FAILED = -3, MAC_INFO_STATUS_BEACON_TIMEOUT = -2, MAC_INFO_STATUS_TX_ACK_TIMEOUT = -1, MAC_INFO_STATUS_OK = 0, MAC_INFO_STATUS_JOIN_ACCEPT_OK = 1 }

enum	mac_network_status_t { NETWORK_UNAVAILABLE = 0, NETWORK_AVAILABLE = 1, NETWORK_UNKNOWN = 2 }

enum	mac_status_t { MAC_STATUS_NOTHING_TO_SEND = -8, MAC_STATUS_DEVICE_OFF = -7, MAC_STATUS_BUSY = -6, MAC_STATUS_FUNCTION_NOT_FOUND = -5, MAC_STATUS_NOT_INITIALIZED = -4, MAC_STATUS_MSG_LENGTH_ERROR = -3, MAC_STATUS_MSG_HEADER_ERROR = -2, MAC_STATUS_NO_NETWORK_JOINED = -1, MAC_STATUS_NO_ERROR = 0 }

Functions
mac_status_t	mac_init (mac_type_t mac, mac_message_callbacks_t cb, mac_battery_callback_t battery_cb, mac_flash_callback_t *flash_cbs)
	Initializes the MAC. More...

mac_status_t	mac_deinit (void)
	Deinitializes the MAC. More...

mac_status_t	mac_init_activation_personalization (uint32_t netid, uint32_t devaddr, uint8_t nwkskey, uint8_t appskey)
	Initiates the Activation By Personalization (ABP). The session keys must be provided. More...

mac_status_t	mac_init_activation_on_air (uint8_t dev_eui, uint8_t app_eui, uint8_t *app_key)
	Initiates the Over The Air Activation (OTAA). Sends a request with the device and application EUI, and waits for a response to compute sessions keys. More...

mac_status_t	mac_send_when_possible (uint8_t port, uint8_t *payload, uint8_t payload_len, downlink_mode_t dl_mode)
	Sends data without acknowledge. More...

mac_status_t	mac_send_when_possible_confirmed (uint8_t port, uint8_t *payload, uint8_t payload_len, uint8_t nb_retries, downlink_mode_t dl_mode)
	Sends data with acknowledge. More...

mac_status_t	mac_network_available (void)
	Reports network availability using callback. It corresponds to the LoRaWAN MAC command Link Check Req. More...

mac_status_t	mac_set_device_class (device_class_t device_class)
	Sets end-device class. (class A, B or C for LoRaWAN, A or C for PicoWAN) More...

mac_status_t	mac_get_device_address (uint32_t *device_address)
	Gets device address. More...

uint16_t	mac_message_max_payload_length (void)
	Returns maximum allowed bytes for user payload. More...

mac_type_t	mac_get_stack (void)
	Returns the stack in use. More...

Detailed Description

MAC unified API for PicoWAN and LoRaWAN network access.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Archos nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND AND EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ARCHOS S.A. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Enumeration Type Documentation

enum downlink_mode_t

Enumerator
DL_DISABLED	Do not wait for downlink.
DL_ENABLED	Wait for downlink.

enum mac_info_status_t

Enumerator
MAC_INFO_STATUS_DUTY_CYCLE_LIMITATION	The MAC cannot send right now due to duty cycle limitation.
MAC_INFO_STATUS_DOWNLINK_DECODING_ERROR	Problem while decoding the received message.
MAC_INFO_STATUS_DOWNLINK_TIMEOUT	No message received.
MAC_INFO_STATUS_RX_ERROR	Problem in the reception.
MAC_INFO_STATUS_TX_MAX_MSG_SIZE_EXCEEDED	Payload length exceed the maximum size allowed.
MAC_INFO_STATUS_MIC_FAILED	Message with the wrong MIC.
MAC_INFO_STATUS_BEACON_TIMEOUT	Too much time to receive a beacon.
MAC_INFO_STATUS_TX_ACK_TIMEOUT	Too much time waiting for TX acknowledge.
MAC_INFO_STATUS_OK	No problem.
MAC_INFO_STATUS_JOIN_ACCEPT_OK	Network is joined.

enum mac_network_status_t

Enumerator
NETWORK_UNAVAILABLE	Network unavailable.
NETWORK_AVAILABLE	Network available.
NETWORK_UNKNOWN	Network unknown.

enum mac_state_t

Enumerator
MAC_STATE_IDLE	MAC is in an idle state.
MAC_STATE_SEARCHING_NETWORK	MAC is searching network.
MAC_STATE_SENDING_DATA	MAC is sending data.
MAC_STATE_WAITING_ACK	MAC is waiting an acknowledge.
MAC_STATE_WAITING_RETRY	MAC is waiting to retry.
MAC_STATE_WAITING_DATA	MAC is waiting data.

enum mac_status_t

Enumerator
MAC_STATUS_NOTHING_TO_SEND	The MAC has nothing to send.
MAC_STATUS_DEVICE_OFF	The device is switched off by software (LoRaWAN only)
MAC_STATUS_BUSY	The MAC is busy doing something.
MAC_STATUS_FUNCTION_NOT_FOUND	Function not implemented for this MAC.
MAC_STATUS_NOT_INITIALIZED	MAC not initialized.
MAC_STATUS_MSG_LENGTH_ERROR	Message length error.
MAC_STATUS_MSG_HEADER_ERROR	Message header error.
MAC_STATUS_NO_NETWORK_JOINED	Impossible to send a message because the network has not been joined.
MAC_STATUS_NO_ERROR	Message successfully sent.

enum mac_type_t

Enumerator
UNDEF_MAC	MAC is not set.
PICOMAC	PicoWAN protocol.
LORAMAC	LoRaWAN protocol.

Function Documentation

mac_status_t mac_deinit ( void )

Deinitializes the MAC.

This function properly deinitializes the MAC by performing all necessary cleanup actions.

Return values

mac_status_t

mac_status_t mac_get_device_address ( uint32_t * device_address )

Gets device address.

This function returns the device address of the current MAC. 0x00000000 is the default device address, before joining a network.

Return values

mac_status_t

mac_type_t mac_get_stack ( void )

Returns the stack in use.

Return values

mac_type_t.

mac_status_t mac_init	(	mac_type_t	mac,
		mac_message_callbacks_t *	cb,
		mac_battery_callback_t *	battery_cb,
		mac_flash_callback_t *	flash_cbs
	)

Initializes the MAC.

This function initializes the MAC layer with the type of MAC and callbacks to use. You can choose between PICOMAC and LORAMAC. Both callbacks, battery_cb and flash_cbs, are dedicated to the LoRaWAN. The battery callback will be called by the MAC to know the battery value of your node, and therefore must be implemented for a working LoRaWAN. The battery level of your node have to be converted to a value between 1 and 254. 0 means your node is connected to an external power source, 255 means that you cannot measure the battery value.

The flash callbacks are used by the MAC to store and load data from the node’s flash. For now, only the LoRa counters in ABP mode needs to be stored.

Use NULL for unused callbacks.

Remarks: flash_cbs only used with LoRaWAN.

Parameters

mac	The MAC to use.
cb	Callback receives informations after every transmission, reception, check of network, and change of MAC state.
battery_cb	Callback will be called by the MAC to know the battery value of your node (LoRaWAN specific).
flash_cbs	Callbacks are used by the MAC to store and load data from the node’s flash (LoRaWAN specific).

Return values

mac_status_t

mac_status_t mac_init_activation_on_air	(	uint8_t *	dev_eui,
		uint8_t *	app_eui,
		uint8_t *	app_key
	)

Initiates the Over The Air Activation (OTAA). Sends a request with the device and application EUI, and waits for a response to compute sessions keys.

This is the second activation mode. In this mode, the node just knows the application EUI and key, as well as the device EUI. Thanks to those, the MAC will try to join the network, which, in turn, will provide the needed keys and IDs to the node.

Parameters

dev_eui	8 bytes array containing the device EUI in little-endian.
app_eui	8 bytes array containing the application EUI in little-endian.
app_key	16 bytes array containing the application key.

Remarks: For now, only used with LoRaWAN.

Return values

mac_status_t

mac_status_t mac_init_activation_personalization	(	uint32_t	netid,
		uint32_t	devaddr,
		uint8_t *	nwkskey,
		uint8_t *	appskey
	)

Initiates the Activation By Personalization (ABP). The session keys must be provided.

This is the first activation mode. This mode is the only one currently available for PicoMAC stack. In this mode, the various keys and IDs are already present in the node, and must be forwarded to the MAC layer. You will have to handle that way the network ID, the device address, and the session keys (NwkSKey and AppSKey).

Parameters

netid	24 bits containing the network identifier.
devaddr	32 bits containing the device address.
nwkskey	16 bytes array containing the network session key.
appskey	16 bytes array containing the application session key.

Return values

mac_status_t

uint16_t mac_message_max_payload_length ( void )

Returns maximum allowed bytes for user payload.

This function returns the maximum length allowed for a message. Note that for PicoMAC max length is 20 bytes.

Return values

uint16_t Max payload length.

mac_status_t mac_network_available ( void )

Reports network availability using callback. It corresponds to the LoRaWAN MAC command Link Check Req.

This function allows to see if your node can reach a gateway. The state will be received by the appropriate callback.

Return values

mac_status_t

mac_status_t mac_send_when_possible	(	uint8_t	port,
		uint8_t *	payload,
		uint8_t	payload_len,
		downlink_mode_t	dl_mode
	)

Sends data without acknowledge.

This function asks the MAC to send a message as soon as possible, without requesting an acknowledge from the network.

Parameters

port	is a number that can be freely chosen between 1 and 223, while 0 is used for MAC commands. Values between 224 and 255 are reserved.
payload	corresponds to the message to send.
payload_len	is the length of the message.
dl_mode	indicates if the MAC should listen for downlink or not (when available).

Return values

mac_status_t

mac_status_t mac_send_when_possible_confirmed	(	uint8_t	port,
		uint8_t *	payload,
		uint8_t	payload_len,
		uint8_t	nb_retries,
		downlink_mode_t	dl_mode
	)

Sends data with acknowledge.

This function does the same thing as mac_send_when_possible(), but also asks an acknowledge from the network.

Parameters

port	is a number that can be freely chosen between 1 and 223, while 0 is used for MAC commands. Values between 224 and 255 are reserved.
payload	corresponds to the message to send.
payload_len	is the length of the message.
nb_retries	allows to set how many times the MAC layer should try to send the message if it does not receive the expected acknowledge.
dl_mode	indicates if the MAC should listen for downlink or not (when available).

Return values

mac_status_t

mac_status_t mac_set_device_class ( device_class_t device_class )

Sets end-device class. (class A, B or C for LoRaWAN, A or C for PicoWAN)

This function allows to select the class to use. For both MAC, you can choose between class A and class C. Those classes correspond respectively to "low power" (the node is listening for incoming data for a short time after transmission) and "high power" (the node is always listening) modes.

Parameters

device_class class to set. [CLASS_A, CLASS_B, CLASS_C]

Return values

mac_status_t

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation