 |
Demo HCI Implementation for WiMOD-LR Devices
V2.0.3
|
|
Demo HCI Implementation for WiMOD-LR Devices
V2.0.3
|
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).
This package currently supports the following LoRa® based protocols:
| 
| 
| 
|
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).
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.
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.
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.
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).
This package is intended to be used in conjunction with a either the WiMOD Shield for Arduino or a WiMODino board.
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).
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.
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.
The HCI protocol defines three different types of messages which are exchanged between the host controller and the radio module:
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
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.
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.
See here for more details.
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 |
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:
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.
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:
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.
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.
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:
Examples for the WiMOD LoRaWAN EndNode Modem firmware:
Examples for the WiMOD LoRaWAN EndNode Modem / WiMOD LR-BASE / WiMOD LR-BASE PLUS / GlobalLink24 firmware using the WiMOD PC-Tools:
or
or
or
Examples for the WiMOD LR-BASE-PLUS firmware:
IoT-Examples using the WiMOD LoRaWAN EndNode Modem + the IoT platform Cayenne / myDevcices features:
Examples for Firmware Update of the WiMOD module using a WiMOD PC Tool:
Examples for the WiMOD GlobalLink24 firmware:
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.
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.
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.
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.
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.
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.
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.
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.
Licensee agrees to use all reasonable efforts to ensure that persons employed by Licensee abide by the terms and conditions of this Agreement.
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.
IMST recognizes two types of termination of License 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.
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.
The provisions contained in Sections 5 and 6 hereof shall survive any termination of this Agreement.
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.
The USER MAY NOT:
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
1.8.17