| Demo HCI Implementation for WiMOD-LR Devices V1.3.1

- Main Page
- Classes
- Files

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 )

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 (see Fig. 1-2). 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 this modules is called HostControlerInterface (HCI).

# Intended Hardware Setup

This package is intended to be used in conjunction with a WiMOD Shield for Arduino.

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).

# 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 "WiMOD_LoRaWAN_EndNode_Modem_HCI_Spec_V1_11.pdf" (or newer) available on https://wireless-solutions.de

# 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 Libraray / 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\Ardunio\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

## 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 firmare
- WiMODLoRaWAN.h: Header file for the LoRaWAN EndNode Modem firmware

## API Object creation

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

- WiMODLRBASE wimod(Serial)
- WiMODLoRaWAN 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:

## 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 a 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

- Examples for the WiMOD LoRaWAN EndNode Modem 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 firmware:

  - 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

- IoT-Examples using the WiMOD LoRaWAN EndNode Modem firmware:

  - LoRaWAN_CayenneDemo: Demo Firmware demonstrating data transfer to myDevices Cayenne platform

## Hint for C++11 platforms

Some boards / plaforms 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 recognises 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,
- sublicense, 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 2017 IMST GmbH, All Rights Reserved

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