| Demo HCI Implementation for WiMOD-LR Devices V2.0.3

WiMOD HCI Driver Implementation for the Arduino® / Genuino Platform

Author
  (FB), IMST GmbH http://wireless-solutions.de

# About

This package is a simple implementation of the WiMODLR HCI interface used for all IMST WiMOD(LR) radio modules (e.g. iM880B , iM881A-M , iM881A-XL , iM282A , iM980B )

The WiMOD (LR) HCI protocol is designed to expose the radio module services to an external host controller. The communication between host and the radio (WiMOD) is based on so called HCI messages which can be sent through a UART interface. The WiMOD LR firmware provides several services for configuration, control and radio link access. These radio modules offer a serial interface for communication. The protocol used for these modules is called HostControlerInterface (HCI).

## Supported Protocols

This package currently supports the following LoRa® based protocols:

### LoRaWAN®

The LoRaWAN® protocol stack, specified by the LoRa Alliance, is based on IBM’s LMiC and IMST’s WiMOD-OS. It enables Low Power Wide Area Networks (LPWANs) for Internet-of-Things (IoT) and Machine-to Machine (M2M) applications and supports Direct or Over The Air Activation (OTAA) as well as Activation By Personalization (ABP).

### ProLink LoRaWAN®

The WiMOD ProLink LoRaWAN® protocol stacks conforms to the LoRaWAN® spec 1.0.4 and additionally includes a Peer-to-Peer Radio Link feature that is compatible to the LR-BASE protocol.

### LR_BASE

The WiMOD LR Base firmware is a collection of functionalities and applications like Radio Link Test, Sensor App., Data Link Service, etc. embedded in our powerful WiMOD OS operating system. It does not include any LoRaWAN functionalities, but it allows direct P2P connections between end nodes.

### LR_BASE_PLUS

The WiMOD LR Base Plus firmware is a collection of functionalities and applications like Radio Link Test, Sensor App., Data Link Service, etc. embedded in our powerful WiMOD OS operating system. It is targeted for 2.4 GHz operation.

### GLOBAL_LINK_24

The WiMOD GlobalLink24 protocol stack is a Low Power Wide Area Network (LPWAN) stack using the LoRa technology on the 2.4 GHz band. By emulating the LoRaWAN protocol stack, it supports Direct or Over The Air Activation (OTAA) as well as Activation By Personalization (ABP).

# Intended Hardware Setup

This package is intended to be used in conjunction with a either the WiMOD Shield for Arduino or a WiMODino board.

## WSA01

For the WiMOD Shield for Arduino the basic setup looks like this:

On the extension board (shield) there should be a WiMOD module running a WiMOD Firmware that uses the HCI Interface for communication purposes (e.g. WiMOD LR_Base, WiMOD LoRaWAN EndNode Modem).

## WiMODino iMxxx

For a WiMODino based hardware the user does to have to do any hardware wirings since the WiMOD module is directly mounted on the main PCB.

# HCI Communication

The communication between the WiMOD LR radio module and a host controller is based on messages. The following chapters describe the general message flow and message format.

## Message Flow

The HCI protocol defines three different types of messages which are exchanged between the host controller and the radio module:

- Command Messages: always sent from the host controller to the WiMOD LR module to trigger a function.
- Response Messages: sent from the radio module to the host controller to answer a preceding HCI request message.
- Event Messages: can be sent from the radio module to the host controller at any time to indicate an event or to pass data which was received over the radio link from a peer device.

For more information about the used Host Controller Interface please refer to the external documents called "WiMOD_LR_Base_HCI_Spec_V1_8.pdf" (or newer) and "ProLink_LoRaWAN_EndNode_Modem_HCI_Spec_V2_0.pdf" (or newer) available on a href="https://wireless-solutions.de/downloadfile/lorawan-software/>LoRaWAN Software and LR-BASE Software

# Package

This package offers a simple demo implementation of the HCI protocol. It allows the user to use a high-level API for communicating to a WiMOD module without having to deal with the low-level details like CRC and SLIP encoding. All low-level details are being handled by the API-Stack itself.

# Installation

In order to install this package / library the user can choose one of these methods:

- Lib Manager of the IDE: The Arduino IDE offers a convenient way to install additional libraries.

  - Start the IDE
  - go "Sketch / Include Library / Add .ZIP Library... " and select the .zip file
  - follow the instructions given by the IDE.

- Manual installation: Copy the contents of the .zip file into your personal Arduino libraries folder:
  - On Windows the folder is located by default at "My Documents\Arduino\libraries"
  - On Linux the folder located by default at "~/Arduino/libraries"
  - For MAC users it folder is likely called "Documents/Arduino/libraries"

See here for more details.

# Usage

## Firmware Compatibility Matrix

Please see below a matrix showing valid hardware / software combinations:

Module | Freq.Band | LR_BASE | LoRaWAN EndNode Modem | LR_BASE+ | GlobalLink24 | ProLink
--- | --- | --- | --- | --- | --- | ---
iM880A/B | 868 MHz | X | X |  |  | X
iM881A-M/-XL | 868 MHz | X | X |  |  | X
iM980A | 915 MHz |  | X |  |  | X
iM282A | 2.4 GHz |  |  | X | X |
iM980B | 868-915 MHz |  | X |  |  | X

## Include files

In order to use the library for custom projects utilizing a WiMOD radio module the user just has to include exactly ONE(!) of the main header files:

- WiMODLR_BASE.h: Header file for the LR_Base firmware
- WiMODLoRaWAN.h: Header file for the LoRaWAN EndNode Modem firmware
- WiMODLR_BASE_PLUS.h: Header file for the LR_Base+ firmware
- WiMODGlobalLink24.h: Header file for the GlobalLink24 firmware
- WiMODProLink.h: Header file for the ProLink firmware

## API Object creation

After including the main header file can create an object or accessing the WiMOD services within the application sketch. The constructor requires a reference to the serial interface that is to be used.

- WiMODLRBASE wimod(Serial)
- WiMODLoRaWAN wimod(Serial)
- WiMODLRBASE_PLUS wimod(Serial)
- WiMODGlobalLink24 wimod(Serial)
- WiMODProLink wimod(Serial)

These files enable the access to the high-level API functions.

For the LR_Base firmware these services are:

For the LoRaWAN firmware these services are:

For the LR_Base+ firmware these services are:

For the GlobalLink24 firmware these services are:

For the LoRaWAN ProLink firmware these services are:

## Setup

Within the Arduino "setup()" function the WiMOD API stack has to be initialized by calling the "wimod.begin()" function. Furthermore the serial interface has to be setup by calling the corresponding "Serial.begin()" function.

## Using the API

After the initial steps the API is ready to be used. The user must call the "wimod.Process()" function in a regular base (e.g. from the "loop()" function) . The "wimod.Process()" call processes all incoming bytes from the serial interface and tries to parse the messages.

## Examples

Within the .zip file there are some basic examples that show use usage of the WiMOD library. If the packet is installed the user will find these examples by clicking on the "File / Examples / WiMOD " menu entries in the IDE.

Most of the provided examples are targeting Arduino® / Genuino boards that support a second serial interface (e.g. Arduino DUE). Using dedicated UARTs has got the advantage of separating the communication session between Arduino / Genuino and WiMOD from the debug communication session between Arduino / Genuino and PC.

- Examples for WiMOD LR_Base firmware:

  - LrBasePing: Simple Sketch demonstrating the usage of a (local) Ping command
  - LrBaseFwInfos: Sketch demonstrating how to get basic information from WiMOD firmware
  - LrBaseSimpleChat:Sketch that implements a simple TX/RX application using the WiMOD radio services
  - LrBaseRTC: Sketch demonstrating the basic usage of the RTC of the WiMOD radio module
  - LrBaseAES: Simple Sketch showing how to set and get the AES key for encrypted communication
  - LrBaseSetRadioConfig: A sketch that demonstrates how to change the current radio configuration
  - ...

- Examples for the WiMOD LoRaWAN EndNode Modem firmware:

  - LoRaWANFwInfos: Sketch demonstrating how to get basic information from WiMOD firmware
  - LoRaWANEndNode_ABP: Sketch demonstrating the ABP procedure to activate the WiMOD to a LoRaWAN server
  - LoRaWANEndNode_OTAA:Sketch demonstrating the registration process via the OTAA procedure
  - LoRaWANEndNode_CDATA: Sketch that transmits 'Hello World' C-Data packets
  - LoRaWANEndNode_CDATA2: Sketch for transmitting and receiving C-Data packets
  - ...

- Examples for the WiMOD LoRaWAN EndNode Modem / WiMOD LR-BASE / WiMOD LR-BASE PLUS / GlobalLink24 firmware using the WiMOD PC-Tools:

  or or or
  - DUE_UartBridge: Simple UART-Bridge for enabling the communication PC <--> WiMOD module using a DUE board
  - Uno_Wimod2PcBridge: Simple UART-Bridge for enabling the communication PC <--> WiMOD module using a UNO board
  - M0_UartBridge: Simple UART-Bridge for enabling the communication PC <--> WiMOD module using a M0 / Zero board
  - ...

- Examples for the WiMOD LR-BASE-PLUS firmware:

  - LrBasePlusFwInfos: Sketch demonstrating how to get basic information from WiMOD firmware
  - LrBasePlusSimpleChat:Sketch that implements a simple TX/RX application using the WiMOD radio services
  - Please see other examples of the LR-BASE section

- IoT-Examples using the WiMOD LoRaWAN EndNode Modem + the IoT platform Cayenne / myDevcices features:

  - LoRaWAN_CayenneDemo: Demo Firmware demonstrating data transfer to myDevices Cayenne platform
  - LoRaWAN_CayenneBME280: Demo Firmware demonstrating data transfer to myDevices Cayenne platform using a BME280 Sensor

- Examples for Firmware Update of the WiMOD module using a WiMOD PC Tool:

  - Uno_BrlBridge: Simple sketch for using the WiMOD bootloader and a DUE board; PLEASE READ THE DOCUMENTATION CAREFULLY
  - DUE_BtlBridge: Simple sketch for using the WiMOD bootloader and a DUE board; PLEASE READ THE DOCUMENTATION CAREFULLY

- Examples for the WiMOD GlobalLink24 firmware:

  - GlobalLink24Ping: Simple Sketch demonstrating the usage of a (local) Ping command
  - GlobalLink24_FwInfos: Sketch demonstrating how to get basic information from WiMOD firmware
  - GlobalLink24_ABP: Sketch demonstrating the ABP procedure to activate the WiMOD module
  - GlobalLink24_OTAA:Sketch demonstrating the registration process via the OTAA procedure
  - Please see other examples of the GlobalLink24 section

# Hint for C++11 platforms

Some boards / platforms support (some) features of the C++11 standard. This library supports the advanced function objects / functions available via the cpp <functional> header file. However not all platforms support this by now. Therefore this library does not use these features by default. The user can turn on this feature by enabling the WIMOD_USE_CPP11 define within the WMDefs.h file.

# Note

This is a demo implementation of the HCI protocol. It is not meant to be most efficient in terms of memory usage and or processing time. The purpose of this implementation is to show to user a complete picture of the message flow and possibilities the HCI interface offers.

Furthermore this implementation does not cover 100 percent of the feature set of the WiMOD modules. The main target is the "normal" application mode and its "normal" usage. Some special features, like hardware / radio tests are not (fully) covered by this demo code.

# EULA - SOFTWARE LICENSE POLICY

Please read the following License Agreement carefully. It is a legal agreement between you (either an individual or a single entity, in the following called Licensee) and IMST GmbH for the software product IMST WiMOD-Communication-Software, in the following called "SOFTWARE". By installing, copying, or otherwise using the SOFTWARE, you as the Licensee agree to be bound by the terms of this agreement. If you do not agree to the terms of this agreement, do not install or use the SOFTWARE; you may, however, return it to IMST or your local seller for a full refund.

## LIMITED LICENSE

IMST herewith grants to Licensee upon payment of the applicable product fee as set forth in the IMST Price List, the limited right and license to utilise the Software, on a non-exclusive and non-transferable single user license basis, for each bought or leased license. Licensee may copy the Software only for backup and archival purposes. Each such copy shall include in readable form all copyright notices contained on the original Software. Licensee may not alter, reproduce, translate, adapt, vary or modify the above-mentioned software.

## LIMITED WARRANTIES

IMST warrants that the Software will perform substantially in accordance with the accompanying written material for a period of 12 months from the date of receipt of the Software. In the case of a leasing contract, warranty period corresponds to the leasing period. Any implied warranties on the Software are limited to the period of six months. Software support, updates and maintenance are not included unless separately agreed upon in purchase order.

## DISCLAIMER OF WARRANTIES, LIMITATIONS OF LIABILITY

To the maximum extent permitted by applicable law, in no event IMST will be liable for any damages whatsoever, including without limitation any indirect, special or consequential damages such as loss of profits or inability to use the Software. In any case, IMST’s entire liability under any provision of this agreement shall be limited to the amount actually paid by Licensee for the Software.

## LICENSEES REMEDIES

IMST entire remedy shall be, at IMST’s option, either (a) return of the price paid, or (b) repair or replacement of the Software that does not meet this warranty. This warranty does not apply, if failure of the Software has resulted from abuse or misapplication. Any replacement Software will be warranted either not longer than the original warranty period or 30 days, whichever is longer.

## EXCLUSIVE PROPERTY

Licensee understands IMST’s statement that the Software is the exclusive and sole property of IMST. Licensee shall not acquire any ownership interest in the Software, but shall only have limited right to use the Software pursuant to this Agreement. Licensee acknowledges that the above mentioned Software may not be assigned, sub-licensed or otherwise transferred without the prior written consent of IMST, except to the successor to that part of licensee’s business to which this Agreement relates. Licensee understand IMST’s statement that any and all of the trade marks, copyrights, patents and other intellectual property rights in most widest sense in connection with the above mentioned software fully belong to IMST, unless otherwise written. None of the rights of Licensee under this Agreement are assignable or transferable without prior written consent of IMST.

## PROTECTION OF TRADE SECRETS

Licensee agrees to use all reasonable efforts to ensure that persons employed by Licensee abide by the terms and conditions of this Agreement.

## MAINTENANCE FEES

Licensee may order maintenance support while the Software is in use by the Licensee. IMST will quote maintenance fee for the Software and renew the appropriate code words yearly. Depending on purchase order, in some cases an initial 12 months software maintenance period is part of purchase order.

## TERMINATION

IMST recognizes two types of termination of License Agreement.

- Discontinuance of policy. Should IMST, at any time discontinue their software policy, IMST will support Licensee through the current year. Licensee may continue use of the Software after that time.
- Breach of License Agreement. In the event of Breach of License Agreement, IMST shall have the right to terminate the Agreement by giving Licensee five days notice of such termination, if Licensee fails to initiate steps to correct such Breach within 30 days after written notice including specific facts of such Breach. In the event of Breach of Agreement, Licensee shall immediately return the Software to IMST at Licensee’s expense.

## ENTIRE AGREEMENT

This Agreement sets forth the entire agreement and understanding between the parties as to the subject matter of this Agreement and merges all prior discussions between them, and neither party shall be bound by any modification of this Agreement, or by any conditions, definitions, warranties, or representations with respect to the subject matter of this Agreement, other than as expressly provided in this Agreement, or as duly set forth on or subsequent to the data hereof in writing and signed by a duly authorised representative of the party to be bound thereby.

## GOVERNING LAW

This Agreement and matters connected with the performance thereof shall be construed, interpreted, applied and governed in all respects in accordance with the law of Germany. ATTORNEY’S FEES. In the event of any suit, action or other litigation involving this Agreement, the prevailing party shall be entitled to recover such party’s attorney’s fees and costs of litigation incurred in connection herewith.

## SURVIVAL

The provisions contained in Sections 5 and 6 hereof shall survive any termination of this Agreement.

## NOTICES

Any notice, request or statement thereunder shall be deemed to be sufficiently given or rendered to the other party, at the beginning of this Agreement or to such other address or persons such party gives notices. Licensee agrees to return a signed copy of this license to IMST.

## RESTRICTIONS

The USER MAY NOT:

- copy and distribute the SOFTWARE or any portion of it,
- sub-license, lease, rent, or transfer this SOFTWARE to another,
- cause or permit reverse engineering, disassembly, decompilation or alteration of this SOFTWARE,
- remove any product identification, copyright notices, or other notices or proprietary restrictions from this SOFTWARE,
- copy the documentation accompanying the SOFTWARE.

The Licensed Materials are for use solely and exclusively with radio frequency devices manufactured by or for IMST or its affiliates.

©copyright 2020 IMST GmbH IMST GmbH, All Rights Reserved

ARDUINO®, and other Arduino brands and logos are Trademarks of Arduino SA