Main include file for the MiraOS library. More...

#include "sys/autostart.h"
#include "sys/process.h"
#include "sys/etimer.h"
#include "mira_gpio.h"
#include "mira_adc.h"
#include "mira_pwm.h"
#include "mira_i2c.h"
#include "mira_spi.h"
#include <stdint.h>

Macros
#define	mira_wait_for_empty_queue()
	Waits until empty TX queue. More...

Typedefs
typedef void(*	MiraReceivedDataCallback) (uint8_t data_ptr, uint8_t length, MiraAddressType address_type, uint8_t address_ptr)
	Function pointer to receive callback. More...

typedef void(*	MiraReceivedMailCallback) (uint8_t *data_ptr, uint8_t length)
	Function pointer to receive callback. More...

Enumerations
enum	MiraErrorType { MIRA_NOERROR = 0, MIRA_ERROR_UNKNOWN_ADDRESS = -1, MIRA_ERROR_UNSUPPORTED_SIZE = -2 }
	Return error codes for Mira library functions. More...

enum	MiraAddressType { MIRA_TO_EUI64 = 0x12, MIRA_TO_ROOT = 0x21, MIRA_TO_LOCAL = 0x41, MIRA_TO_BROADCAST = 0x81 }
	Supported addressing modes for Mira messages. More...

enum	MiraAntennaType { MIRA_CHIP_ANTENNA = 0, MIRA_EXT_ANTENNA = 1 }
	Antenna options. More...

enum	MiraConnectionStatus { MIRA_CONNECTION_HAS_NOT_SYNCHRONIZED, MIRA_CONNECTION_HAS_SYNCHRONIZED, MIRA_CONNECTION_HAS_JOINED }
	Connection status. More...

enum	MiraSerialCommandInterfaceMode { MIRA_SERIAL_COMMAND_INTERFACE_DISABLED = 0, MIRA_SERIAL_COMMAND_INTERFACE_ENABLED }

Functions
MiraErrorType	mira_send_data (MiraAddressType address_type, uint8_t address_ptr, uint8_t data_ptr, uint8_t length)
	Function to send a data message. More...

uint8_t	mira_tx_queue_is_empty (void)
	TX queue empty check. More...

void	mira_register_data_received_callback (MiraReceivedDataCallback callback)
	Register the received data callback. More...

void	mira_enable_data_forwarding ()
	Enable forwarding of data messages to the command serial port. More...

void	mira_disable_data_forwarding ()
	Disable forwarding of data messages to the command serial port. More...

void	mira_register_mail_received_callback (MiraReceivedMailCallback callback)
	Register the received data callback for mails to sleepy nodes. More...

int8_t	mira_check_mailbox (void)
	Check for mails. More...

void	mira_set_credentials (uint16_t pan_id, uint8_t *aes_key)
	Sets the network credentials to use. More...

void	mira_become_root (void)
	Become the network root. More...

void	mira_commit_network_setup (void)
	Commit the network setup and start routing traffic. More...

void	mira_set_name (char *name)
	Set the node name. More...

MiraConnectionStatus	mira_get_connection_status (void)
	Get the current network connection status. More...

void	mira_select_antenna (MiraAntennaType antenna)
	Selects the antenna option. More...

void	mira_disable_rf_frontend (void)
	Disables the RF frontend. More...

void	mira_enable_rf_frontend (void)
	Enables the RF frontend. More...

void	mira_reboot (void)
	Reboots the module. More...

void	mira_init (MiraSerialCommandInterfaceMode serial_command_interface_mode)
	Initializes the library. More...

void	mira_init_bootloader (MiraSerialCommandInterfaceMode serial_command_interface_mode, uint16_t firmware_image_id)
	Initializes the library in bootloader mode. More...

void	mira_set_fw_encryption_key (uint8_t *key)
	Sets the encryption key to be used for firmware update files. More...

void	mira_copy_board_eui (uint8_t *eui_ptr)
	Get the board EUI-64. More...

void	mira_leave_fwup_process (void)
	Leaves a firmware update process. More...

Variables
process_event_t	mira_tx_queue_empty_event
	Event for that the TX queue now is empty.

Detailed Description

Main include file for the MiraOS library.

Author: LumenRadio AB

Date: 17 Jan 2016 The MiraOS library provides functions for controlling the Mira radio module, sending/receiving messages, controlling peripherals, etc.

See also: http://docs.lumenrad.io/mira

Macro Definition Documentation

◆ mira_wait_for_empty_queue

#define mira_wait_for_empty_queue ( )

Value:

{ \
    while (!mira_tx_queue_is_empty()) { \
        PROCESS_PAUSE(); \
    } \
}

Waits until empty TX queue.

This function checks if the message queue is empty, if it's not empty it will block until the queue becomes empty.

Returns: void

Typedef Documentation

◆ MiraReceivedDataCallback

typedef void(* MiraReceivedDataCallback) (uint8_t *data_ptr, uint8_t length, MiraAddressType address_type, uint8_t *address_ptr)

Function pointer to receive callback.

Parameters

data_ptr	a pointer to the received data
length	the length of the received data
address_type	addressing mode that was used for the message
address_ptr	a pointer to the destination address, NULL of none.

Returns: void

◆ MiraReceivedMailCallback

typedef void(* MiraReceivedMailCallback) (uint8_t *data_ptr, uint8_t length)

Function pointer to receive callback.

Parameters

data_ptr	a pointer to the received data
length	the length of the received data

Returns: void

Enumeration Type Documentation

◆ MiraAddressType

enum MiraAddressType

Supported addressing modes for Mira messages.

Enumerator
MIRA_TO_EUI64	EUI64 destination address
MIRA_TO_ROOT	Send to network root (no address needed)
MIRA_TO_LOCAL	Send to local neighbours (no address needed)
MIRA_TO_BROADCAST	Broadcast to entire network (no address needed)

◆ MiraAntennaType

enum MiraAntennaType

Antenna options.

Enumerator
MIRA_CHIP_ANTENNA	Integrated chip antenna
MIRA_EXT_ANTENNA	Antenna connector for external antenna

◆ MiraConnectionStatus

enum MiraConnectionStatus

Connection status.

Enumerator
MIRA_CONNECTION_HAS_NOT_SYNCHRONIZED	The channel hopping has not yet synchronized
MIRA_CONNECTION_HAS_SYNCHRONIZED	The channel hopping has synchronized but the node has not joined a network
MIRA_CONNECTION_HAS_JOINED	The node has joined a network. A network root has been found

◆ MiraErrorType

enum MiraErrorType

Return error codes for Mira library functions.

Enumerator
MIRA_NOERROR	Success
MIRA_ERROR_UNKNOWN_ADDRESS	Unknown address type
MIRA_ERROR_UNSUPPORTED_SIZE	Message is larger than allowed

Function Documentation

◆ mira_become_root()

void mira_become_root ( void )

Become the network root.

Each network must have a network root that sets up the network and coordinates and synchronizes the frequency hopping as well as setting up routes. Calling this function causes this node to become a root. Currently, there may not be more than one root on one network at a time.

Returns: void

◆ mira_check_mailbox()

int8_t mira_check_mailbox ( void )

Check for mails.

For sleepy nodes that are not part of the full network, this function can be called to check its mailbox in its neighbor nodes.

Returns: 1 if mail was available, 0 if none was available, another value in case of error.

◆ mira_commit_network_setup()

void mira_commit_network_setup ( void )

Commit the network setup and start routing traffic.

When setting up the network, this function shall be called to make all network settings take effect. This will start the routing protocol. If this function is not called, only broadcast traffic will work.

Returns: void

◆ mira_copy_board_eui()

void mira_copy_board_eui ( uint8_t * eui_ptr )

Get the board EUI-64.

Gets the Mira module's EUI-64 address.

Parameters

eui_ptr a pointer to a 8 byte buffer where the EUI-64 will be copied to.

Returns: void

◆ mira_disable_data_forwarding()

void mira_disable_data_forwarding ( )

Disable forwarding of data messages to the command serial port.

@ return void

◆ mira_disable_rf_frontend()

void mira_disable_rf_frontend ( void )

Disables the RF frontend.

If RF frontend is disabled, the module will run at the maximum output power it can without the PA. Note: this also disables the LNA.

Returns: void

◆ mira_enable_data_forwarding()

void mira_enable_data_forwarding ( )

Enable forwarding of data messages to the command serial port.

@ return void

◆ mira_enable_rf_frontend()

void mira_enable_rf_frontend ( void )

Enables the RF frontend.

This enabled both PA and LNA in the RF frontend. The module will consume some more energy, but will get greater range due to better receiver sensitivity and higher output power.

Returns: void

◆ mira_get_connection_status()

MiraConnectionStatus mira_get_connection_status ( void )

Get the current network connection status.

Returns: Network connection status

◆ mira_init()

void mira_init ( MiraSerialCommandInterfaceMode serial_command_interface_mode )

Initializes the library.

The Mira library must be initialized before any other mira functions are used. Failure to do so may result in unexpected behaviour.

Parameters

enabled_serial_command_interface Enables the UART API interface. See the UART API interface specification.

Returns: void

◆ mira_init_bootloader()

void mira_init_bootloader	(	MiraSerialCommandInterfaceMode	serial_command_interface_mode,
		uint16_t	firmware_image_id
	)

Initializes the library in bootloader mode.

The Mira library must be initialized before any other mira functions are used. Failure to do so may result in unexpected behaviour.

Parameters

enabled_serial_command_interface	Enables the UART API interface. See the UART API interface specification.
firmware_image_id	Version id of the current firmware

Returns: void

◆ mira_leave_fwup_process()

void mira_leave_fwup_process ( void )

Leaves a firmware update process.

Calling this functions leaves any ongoing firmware update process, or refrain to be part of one that gets started.

Returns: void

◆ mira_reboot()

void mira_reboot ( void )

Reboots the module.

Returns: void

◆ mira_register_data_received_callback()

void mira_register_data_received_callback ( MiraReceivedDataCallback callback )

Register the received data callback.

The received data callback will be called every time a new data message is received.

Parameters

callback a function pointer to the callback function

Returns: void

◆ mira_register_mail_received_callback()

void mira_register_mail_received_callback ( MiraReceivedMailCallback callback )

Register the received data callback for mails to sleepy nodes.

The received data callback will be called if a mailbox contains a mail to this device.

Parameters

callback a function pointer to the callback function

Returns: void

◆ mira_select_antenna()

void mira_select_antenna ( MiraAntennaType antenna )

Selects the antenna option.

Selects if to use the internal chip antenna or if to use the antenna connector connected to an external antenna.

Parameters

antenna the antenna option to use.

Returns: void

◆ mira_send_data()

MiraErrorType mira_send_data	(	MiraAddressType	address_type,
		uint8_t *	address_ptr,
		uint8_t *	data_ptr,
		uint8_t	length
	)

Function to send a data message.

Parameters

address_type	adressing mode to use for this message
address_ptr	pointer to the destination address, format must match address_type parameters
data_ptr	pointer to the data to be sent
length	the length of the data

Returns: MiraErrorType

◆ mira_set_credentials()

void mira_set_credentials	(	uint16_t	pan_id,
		uint8_t *	aes_key
	)

Sets the network credentials to use.

Each network uses a set of credentials to be able to communicate. Network ID (aka. PAN ID) and AES encryption key need to be set to be able to participate in the communication on a network. This function overrides whatever may (or may not) be set using the comissioning application.

Parameters

pan_id	the PAN ID (network ID) to use
aes_key	a pointer to the AES key to use

Returns: void

◆ mira_set_fw_encryption_key()

void mira_set_fw_encryption_key ( uint8_t * key )

Sets the encryption key to be used for firmware update files.

This must be the same used to encrypt the firmware from the Makefile. This function must be called before the call to mira_init or mira_init_bootloader. If not called the key will default to {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F}.

Parameters

key	pointer to a 128 bit encryption key

Returns: void

◆ mira_set_name()

void mira_set_name ( char * name )

Set the node name.

Sets the human readable node name for this node. This name will be returned as the device label of this node in the network statistics commands.

Parameters

name	A pointer to a null terminated string with the name.

Returns: void

◆ mira_tx_queue_is_empty()

uint8_t mira_tx_queue_is_empty ( void )

TX queue empty check.

Returns the Mira TX message queue status.

Returns: tx queue empty flag

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ mira_wait_for_empty_queue

Typedef Documentation

◆ MiraReceivedDataCallback

◆ MiraReceivedMailCallback

Enumeration Type Documentation

◆ MiraAddressType

◆ MiraAntennaType

◆ MiraConnectionStatus

◆ MiraErrorType

Function Documentation

◆ mira_become_root()

◆ mira_check_mailbox()

◆ mira_commit_network_setup()

◆ mira_copy_board_eui()

◆ mira_disable_data_forwarding()

◆ mira_disable_rf_frontend()

◆ mira_enable_data_forwarding()

◆ mira_enable_rf_frontend()

◆ mira_get_connection_status()

◆ mira_init()

◆ mira_init_bootloader()

◆ mira_leave_fwup_process()

◆ mira_reboot()

◆ mira_register_data_received_callback()

◆ mira_register_mail_received_callback()

◆ mira_select_antenna()

◆ mira_send_data()

◆ mira_set_credentials()

◆ mira_set_fw_encryption_key()

◆ mira_set_name()

◆ mira_tx_queue_is_empty()