Documentation

Mistake on this page? Email us
Docs › Connecting devices › End-to-end tutorials › Izuma Border Router tutorial › Izuma Border Router

Izuma Border Router

Izuma Border Router is a Izuma Device Management-enabled border router implementation that provides the Wi-SUN border router logic.

A border router is a network gateway between a wireless Wi-SUN mesh network and a backhaul network. It controls and relays traffic between the two networks. In a typical setup, a Wi-SUN border router is connected to another router in the backhaul network (over Ethernet), which in turn forwards traffic to and from the internet or a private company LAN.

The code layout is organized like this:

configs/                  Contains Mbed TLS configs and Wi-SUN Certificates
bootloader/               Contains Bootloader for DISCO_F769NI and MIMXRT1050_EVK platform
mbed_app.json             Build time configuration file

Prerequisites

To work with the Izuma Border Router application, you need:

  • Either the Disco_F769NI or NXP MIMXRT1050-EVK development board.

  • Serial connection to your device with open terminal connection (baud rate 115200, 8N1). This is optional but helps with debugging and confirming that the client connects to Device Management and the Wi-SUN interface is up.

  • Arm Mbed CLI installed. See installation instructions.

    Make sure that all the Python components align with the pip package requirements.txt list from Mbed OS.

  • Izuma Device Management account.

  • An API key with Administrators group privilages for your Device Management account. The API key is needed for automatically generating the developer certificate and for firmware update.

Memory consumption

On a border router, the memory needed on board depends on network size. The RAM memory needed for a node on a network is about 650B. The needed KV store size for a node is about 100B. KV store is needed to store Wi-SUN parameters during power cycle. Some Wi-SUN parameters must be stored to KV store periodically (for example, once in an hour). The size of periodically stored parameters is less than 100B.

Configuring and compiling the Izuma Border Router application for DISCO_F769NI

  1. Clone the repository:

    git clone https://github.com/PelionIoT/pelion-border-router.git

  2. Go to pelion-border-router, and deploy the dependencies:

    cd pelion-border-router
mbed deploy

  3. Configure your device for your Device Management account and credentials.

  4. Download a developer certificate from Device Management Portal.

  5. Copy the mbed_cloud_dev_credentials.c file to the root folder of the example application.

  6. Create update-related configuration and credentials using the manifest tool Python package:

    1. Upgrade to manifest-tool version 2.4.1 or higher:

      pip install --upgrade manifest-tool

      Note: If your host system Python version is 3.6, use manifest-tool version 2.4.1. Use version 2.5.0 (or newer) for a more up-to-date system. You can specify the version via: pip install manifest-tool==2.4.1.

    2. Initialize the developer environment:

      manifest-dev-tool init --access-key <Device Management access key>

    Note: When you create a firmware update image for a deployed device, you must use the same update-related configuration and credentials (update private key, public key certificate, update_default_resources.c and configuration files) you used in the original device firmware image. Therefore, you need to skip running this command because your environment should be already initialized.

  7. Configure the application for your Wi-SUN network:

    1. Use the Wi-SUN certificate definitions file configs/wisun_certificates.h, or generate your own Wi-SUN certificates (recommended) file to the same location.
    2. Ensure the required Wi-SUN certificates (in file configs/wisun_certificates.h) are valid (WISUN_ROOT_CERTIFICATE, WISUN_SERVER_CERTIFICATE, WISUN_SERVER_KEY) and match the settings you are using with the border router. Invalid certificates or certificates that don't match prevent mesh network formation.

    Tip: Use the same Mbed OS version in the border router and the application (Device Management Client).

    Note: For security reasons, when you go to production, please don't use the example Wi-SUN certificate files provided without modifications.

  8. Configure Wi-SUN:

    The mbed_app.json file contains configuration for the Izuma Border Router application.

    The Wi-SUN specific parameters are:

    Field Description
    wisun-network-name Network name for Wi-SUN the network, MUST be the same for all the devices in the network
    wisun-regulatory-domain Defines regulatory domain, refer to ws_management_api for correct values for your region
    wisun-operating-class Defines operating class, limited by the regulatory domain
    wisun-operating-mode Defines the operating mode, limited by the regulatory domain
    wisun-uc-channel-function Unicast channel function
    wisun-bc-channel-function Broadcast channel function
    wisun-uc-fixed-channel Fixed channel for unicast
    wisun-bc-fixed-channel Fixed channel for broadcast
    wisun-uc-dwell-interval Unicast dwell interval. Range: 15-255ms
    wisun-bc-interval Broadcast interval. Duration between broadcast dwell intervals. Range: 0-16777216ms
    wisun-bc-dwell-interval Broadcast dwell interval. Range: 15-255ms
    certificate-header Wi-SUN certificate header file
    root-certificate Root certificate
    own-certificate Own certificate
    own-certificate-key Own certificate's key

    Regulatory domain, operating class and operating mode are defined in the Wi-SUN PHY specification.

  9. Ensure backhaul connectivity:

    Make sure the Izuma Border Router application is connected to a backhaul network. This enables the border router to connect to the Izuma server as well as the Wi-SUN mesh network to the internet or a private LAN. The application supports Ethernet backhaul connectivity.

  10. Enable dual-bank mode on DISCO_F769NI:

    1. Connect the device using STLink-Utility software
    2. Go to Target > Option Bytes. Uncheck nDBANK.
    3. Apply, and disconnect.

  11. Compile the application for DISCO_F769NI:

    mbed compile -m DISCO_F769NI -t GCC_ARM

Enabling external RADIUS server interface

You can enable external RADIUS server interface on the Izuma Border Router by setting the RADIUS server IPv6 address and shared secret on Wi-SUN configuration through mbed_app.json.

The external RADIUS server specific parameters are:

| Field                               | Description                                                   |
|-------------------------------------|---------------------------------------------------------------|
| `radius-server-ipv6-address`        | RADIUS Server IPv6 address in string format (e.g. \"2001:1234::1\") |
| `radius-shared-secret`              | RADIUS shared secret; ASCII string or sequence of bytes |
| `radius-shared-secret-len`          | RADIUS shared secret length; If length is not defined, strlen() is used to determine RADIUS shared secret length |

Running the Izuma Border Router application

  1. Find the binary file pelion-border-router.bin in the BUILD folder.

  2. Copy the binary to the USB mass storage root of the development board. It is automatically flashed to the target MCU. When the flashing is complete, the board restarts itself.

    Press the Reset button of the development board if it does not restart automatically.

  3. The program begins execution.

  4. Open the serial connection, for example PuTTY.

  5. Obtain your device's Device ID either from device console logs or from Device Management Portal. When the client has successfully connected, the terminal shows:

    Client registered
Endpoint Name: <Endpoint name>
Device ID: <Device ID>

  6. To verify the connection with Device Management Portal:

    1. Log in to Device Management Portal.
    2. Select Device Directory from the menu on the left.
    3. When your device is listed on the Devices page, the device is connected and available.

Your device is now connected and ready for the firmware update. For development devices, the Endpoint name and Device ID are identical.

Updating the firmware

  1. To update the firmware on your device:

    manifest-dev-tool update \
     --payload-path pelion-border-router_update.bin \
     --device-id <Device ID>
     --wait-for-completion

  2. When the update starts, the client tracing log shows:

    [FOTA] Updating component MAIN from version 0.0.0 to 0.0.2'

  3. After this, the device reboots automatically and registers to Device Management.

Program flow

  1. Initialize, connect and register to Izuma Device Management.
  2. Initialize and bring up the Wi-SUN interface.

Serial connection settings

Serial connection settings are:

  • Baud-rate = 115200.
  • Data bits = 8.
  • Stop bits = 1.

If there is no input from the serial terminal, press the Reset button of the development board.

In the PuTTY main screen, save the session, and click Open. This opens a console window showing debug messages from the application. If the console screen is blank, you may need to press the Reset button of the board to see the debug information. The serial output from the Izuma Border Router looks something like this in the console:

[INFO][App ]: Izuma Border Router Application
[INFO][App ]: Fetching Backhaul Interface
[INFO][App ]: Fetching Mesh Interface
[INFO][App ]: Connect to Backhaul Interaface
[INFO][IPV6]: Start Bootstrap
[INFO][addr]: Tentative Address added to IF 1: fe80::280:e1ff:fe24:1c
[INFO][addr]: DAD passed on IF 1: fe80::280:e1ff:fe24:1c
[INFO][addr]: Tentative Address added to IF 1: 2001:14b8:1830:b000:280:e1ff:fe24:1c
[INFO][icmp]: Route: ::/0 Lifetime: 60 Pref: 0
[INFO][Ndns]: DNS Server: 2001:14b8:1830:8000::1 from: fe80::208:a2ff:fe0d:53 Lifetime: 60
[INFO][Ndns]: DNS Search List: 0b:6c:6f:63:61:6c:64:6f:6d:61:69:6e:00 Lifetime: 60
[INFO][icmp]: Route: ::/0 Lifetime: 60 Pref: 0
[INFO][Ndns]: DNS Server: 2001:14b8:1830:8000::1 from: fe80::208:a2ff:fe0d:53 Lifetime: 60
[INFO][Ndns]: DNS Search List: 0b:6c:6f:63:61:6c:64:6f:6d:61:69:6e:00 Lifetime: 60
[INFO][addr]: DAD passed on IF 1: 2001:14b8:1830:b000:280:e1ff:fe24:1c
[INFO][IPV6]: IPv6 bootstrap ready
[INFO][App ]: Backhaul Interface connected with IP 2001:14b8:1830:b000:280:e1ff:fe24:1c

Setting up a mesh network with Izuma Border Router

To set up a mesh network using Izuma Border Router, see our Wi-SUN tutorial.

Previous Next