Skip to content

Licensing tool

Each node (implementing MiraOS, MiraMesh, or Border Gateway radio) needs a unique license from a license generator.

Every license is unique to the device, and cannot be copied from one device to another.

mira_license is a python script used to work with licenses and license dongles.

Instructions for installation of it is in the README.md file in the libmira/tools directory.

The first argument to the script says what sub-command to run.

To see the available sub-commands, run:

./mira_license.py -h

To see the available arguments to a sub-command, in this example the "report" sub-command, run:

./mira_license.py report -h

Reading a status report from a License Generator

Use the mira_license.py tool.

./mira_license.py report -d /dev/ttyXXXXX

or

./mira_license.py report -d /dev/ttyXXXXX -F filename

Where /dev/ttyXXXXX is the device name for the License Generator UART interface.

The command generates a license report and either writes it the given filename or it is shown as output from the program.

The report shows the number of generated licenses, as well as the number of allowed licenses for this license dongle.

Reading the device ID of a connected device

To read the device ID of an NRF device, use:

./mira_license.py get_device_id -d /dev/ttyXXXXX -P nrfjprog -s NNNNN

To read the device ID of an mkw41z device, use:

./mira_license.py get_device_id -d /dev/ttyXXXXX -P nxp_mkw41z -s NNNNN

Where /dev/ttyXXXXX is the device name for the License Generator UART interface. NNNNN is the serial number of the programmer, which can be retrieved using nrfjprog --ids. If -s NNNNN is not provided, one of the connected device's serial numbers are used.

The device ID is printed on the command line interface.

Signing a connected device

To sign an NRF device, when the license dongle is connected to the computer, run:

./mira_license.py license -d /dev/ttyXXXXX -P nrfjprog -s NNNNN -a AAAAA -l LLLLL

To sign an mkw41z device, use:

./mira_license.py license -d /dev/ttyXXXXX -P nxp_mkw41z -s NNNNN -a AAAAA -l LLLLL

Where /dev/ttyXXXXX is the device name for the License Generator UART interface.
NNNNN is the serial number of the programmer, which can be retrieved using nrfjprog --ids. AAAAA is the origin of the 'CERTIFICATE' area in the .ld script of the target.
LLLLL is the length of the 'CERTIFICATE' area in the .ld script of the target.

Generating license for a remote device

To generate licenses remotely the device ID must be specified. The device ID can be read out by this tool, is printed by MiraOS upon startup, and can be supplied at runtime via the Mira API, see API documentation. The license will be saved to a file.

./mira_license.py generate -d /dev/ttyXXXXX -i IIIII -F FILE

Where /dev/ttyXXXXX is the device name for the License Generator UART interface.
IIIII is the device ID of the target.
FILE is the name of the file created. The file is in text format, and the license is in Base64.

The license can also be saved in Intel HEX format. In that case address and length must be specified.

./mira_license.py generate -d /dev/ttyXXXXX -P ihex -a AAAAA -l LLLLL -i IIIII -f FILE

Signing a device with remotely generated license

./mira_license.py license -P PROG -a AAAAA -l LLLLL -I FILE

Where PROG is the programmer.
AAAAA is the origin of the 'CERTIFICATE' area in the .ld script of the target.
LLLLL is the length of the 'CERTIFICATE' area in the .ld script of the target.
FILE is the name of the license file. Must be a textfile generated with generate and -f arguments.

Signing a gateway

./mira_license.py generate -d /dev/ttyXXXXX -i NNNNN -F NNNNN.lic

Put the created NNNNN.lic file in the licenses sub-directory.

Where /dev/ttyXXXXX is the device name for the License Generator UART interface.
NNNNN is the device id of the gateway's radio. The gateway will write the device name in its logs when the license is missing.

Changing the license storage

The address (-a) and length (-l) of the certificate block can be changed for a given build, to match the 'CERTIFICATE' space in the .ld script, when using a custom ld script. For more information, see:

./mira_license.py -h

Updating a license file or node's license

A license file or a node can be updated with/without frontend configuration.

To remove a frontend configuration from a license file, run:

./mira_license.py update -I IN-FILE -F OUT-FILE

To add a frontend configuration from a license file, run:

./mira_license.py update -I IN-FILE -F OUT-FILE -C CONFIG-FILE

The update command can also add/remove the frontend configuration on a node. It uses the same command line arguments as license.

To remove the frontend configuration from a node run:

./mira_license.py update -P PROG -a AAAAA -l LLLLL

where AAAAA is the address (from the CERTIFICATE section in the ld-script), LLLLL is the length and PROG is nrfjprog or nxp_mkw41z.

To add frontend configuration to a node run:

./mira_license.py update -P PROG -a AAAAA -l LLLLL -C CONFIG-FILE

where CONFIG-FILE is the frontend configuration file.

Configuring a radio frontend

The license, generate and update commands take optional "-C FILE" arguments. The FILE argument points to a configuration file for the frontend.

Format

The format of the configuration file is json, extended to support C-style comments. The format looks like this:

/*
 * Fronend configuration for a FE like this on nRF52:

 * CPS = P1.11
 * CSD = P1.10
 * CTX = P1.12
 * CRX = P1.14
 *
 * TX bypass = CPS=0 CSD=1 CRX=0 CTX=1
 * TX active = CPS=1 CSD=1 CRX=0 CTX=1
 * RX bypass = CPS=0 CSD=1 CRX=1 CTX=0
 * RX active = CPS=1 CSD=1 CRX=1 CTX=0
 * idle      = CPS=0 CSD=0 CRX=0 CTX=0
 *
 * ANTSEL = P1.06
 *
 * ANTSEL idle = ANTSEL=0
 * ANTSEL 0    = ANTSEL=0
 * ANTSEL 1    = ANTSEL=1
 */
{
    /* In cB (centi-bel, or tenth of dB) */
    "gain_cb_bypass_tx": -30, /**< gain in bypass TX [cB] */
    "gain_cb_active_tx": 300, /**< gain in PA active TX [cB] */
    "gain_cb_bypass_rx": -30, /**< gain in bypass RX [cB] */
    "gain_cb_active_rx": 115, /**< gain in PA active RX [cB] */

    /** Set unused GPIO pins to MIRA_GPIO_PIN_UNDEFINED */
    "gpio_mode_control":[
        [1,12], /* CTX */
        [1,14], /* CRX */
        [1,10], /* CSD */
        [1,11]  /* CPS */
    ], /**< GPIO for PA mode control */
    "gpio_antsel":[[1,6]], /**< GPIO for antenna selection */

    "pin_values_bypass_tx":5, /**< GPIO levels to select bypass TX mode */
    "pin_values_active_tx":13, /**< GPIO levels to select PA active TX mode */
    "pin_values_bypass_rx":6, /**< GPIO levels to select bypass RX mode */
    "pin_values_active_rx":14, /**< GPIO levels to select PA active RX mode */
    "pin_values_idle":0, /**< GPIO levels to set the PA in idle mode */

    "pin_values_antsel":[0, 1, 0, 0], /**< GPIO levels required for gpio_antsel
                                   * to select antenna. Only bit 0 is used. */
    "pin_values_antsel_idle":0, /**< GPIO levels required for gpio_antsel
                                     * to enter idle mode */
}

API

To check license validity at runtime, see API documentation