Modules Overview

BlueRange Mesh consists of a number of different modules. There are the core modules which are part of the open source distribution, which deliver standard functionality. Also, there are other modules, some developed by us or by other developers that can provide specific functionality and built on our mesh framework.

General

All modules share a set of commands for loading and retrieving their configuration, for activating and deactivating them and for triggering actions.

Each custom module should extend the Module class to have a set of methods that it can override. Some of these methods are explained below:

Method Description

Module Constructor

The constructor must only define variables and should not start any functionality.

ConfigurationLoadedHandler

This handler is called once the module should be initialized. A pointer to the configuration will be given and all initialization should happen in this method. If the module configuration says that the module is inactive, the module should not initialize any functionality.

TimerEventHandler

Will be called at a fixed interval for all Modules. If functionality should only be executed e.g. each 5 seconds, use the SHOULD_IV_TRIGGER macro in the handler.

TerminalCommandHandler

Will receive all terminal input that can then be checked against a list of commands to execute.

ButtonHandler

Called once a button has been pressed and released.

MeshMessageReceivedHandler

Will be called once a full message has been received over the mesh (e.g. after all message parts were reassembled)

BleEventHandler

Implement this to receive all other ble events that have not been preprocessed, such as received advertising packets, new connections, e.g.

PreEnrollmentHandler

Allows a module to e.g. enroll an attached controller before accepting the enrollment. Check the EnrollmentModule for more info.

RecordStorageEventHandler

When saving a record, this handler is called once the flash access was done. Check the RecordStorage documentation.

CheckMeshAccessPacketAuthorization

See MeshAccessModule

CheckComponentUpdateRequest

Implement to ask a 3rd party controller about compatibility with the Dfu.

StartComponentUpdate

Called once the Dfu image is ready and can be sent to a 3rd party controller.
Commands are given with arguments in brackets [arg]. These must be entered by the user. Arguments in curly brackets {arg} are optional.

Module Configuration

Every module in fruitymesh has its own configuration and version number. This configuration is automatically loaded from flash during booting, provided that it has same configuration version number as the currently running firmware and has the same or less configuration size than the already existing one. If one wishes to increase the version number then the configuration must be manually migrated. Default configuration is loaded first and is later on overwritten by the loaded configuration in full or parts. Afterwards, once module configuration is successfully loaded, it is then put into ram. The method in UtilityModule (Utility::SaveModuleSettingsToFlash(…​.)) could be used to store module configuration. This method uses RecordStorage with moduleId as a recordId to store module configurations. Refer to RecordStorage to get more information on how to store and extract data using Record Storage. Node Module configuration is erased after unenrolling the BlueRange device and is updated to new configuration provided during enrollment message after the BlueRange device is enrolled.

Set Module Configuration

Sends a new module configuration to any node. The resulting binary configuration will be copied to the modulen configuration of the specified module.

set_config [nodeID | "this"] [module-name] [hex-string] {requestHandle}

//Set binary configuration for io module
set_config 0 io 06:01:01:00:00 0

Request Module Configuration

Prints the configuration of a specific module.

//Display the current module configuration, shorthand notation is: getconf
get_config [nodeID  | "this"] [module name]

//Print the configuration from the current node's advertising module
get_config this adv

Activate & Deactivate Module At Runtime

Activates or deactivates a specific module.

//Activate or deactivate a module, shorthand notation is: setactive
set_active [nodeID | "this"] [module name] [on | off]

//Examples
set_active 0 scan on //activates the scan module
set_active 0 adv off //deactivates the advertising module

Once received, the message is replied by the following message:

{
    "nodeId":2,
    "type":"set_active_result",
    "module":6,
    "requestHandle":0,
    "code":0
}

Where "code" can have one of the following values:

Value

Description

0

SUCCESS

1

NO_CONFIGURATION, the module was activate/deactivated but it was impossible to save the state as the module seems to have no configuration. (Report this to a firmware developer if it ever happens.)

2

NO_SUCH_MODULE, the given module does not exists.

3

RECORD_STORAGE_ERROR, the module does exist and does have a configuration but the record storage was unable to save the config. The best course of action is probably to try again later as the node seems to be busy right now.

Module List (version 2)

This is the response to the get_modules command.

The Module List message provides information about available modules on a given device with some details like their moduleId, their version and whether they are currently active. This information can be used to find out, what a node is capable of doing.

{
    "nodeId": 1,
    "type": "module_list",
    "modules": [
        {
            "id": 1,
            "version": 2,
            "active": 1
        },
        {
            "id": 2,
            "version": 1,
            "active": 0
        },
        // ...
    ]

name

bytes

Description

ModuleIdWrapper

4

Module ID.

moduleVersion

1

Module version.

moduleActive

1 bit

1 if active, 0 if not active.

reserved

7 bits

Reserved for future use.

…​

Module Commands

Most module commands are structured in the same way. You have to give the nodeId that should process the command, specify the module and a command that should be triggered.

//Trigger some module action, shorthand notation is: action
action [nodeID  | "this"] [module name] [command]

//Examples
action 0 io led on //Switch on the LED for all connected nodes
action this io led off //Switch off LEDs for the current node
action 0 status get_device_info //Get the device info of all nodes
action 123 status get_status //Get the current status from node 123

Open Source Modules

The following modules are currently part of the open source release:

Proprietary Modules