Getting Started With Helium, PlatformIO and Heltec CubeCell
- CubeCell series has three branches that can be listed as Module, Dev-Board and Capsule Sensor. The Dev-board can be controlled with AT commands. As mentioned earlier it also supports Arduino programming in Windows, Mac OS, and Linux.
- CubeCell HTCC-AC01 is a LoRa end node sensor and independent wireless sensor product. With a complete enclosure and protection measures, it can be deployed directly into real-world applications. Compatible with Windows, Linux, Mac OS three major operating systems 9. The sensor can be replaced at will 10. Can be used for network formation.
The Heltec CubeCell HTCC AB0x are one of Heltec's line of popular ASR605x(ARM®Cortex® M0+ Core) based LoRa development boards with built in USB and batterycharging.
The Heltec CubeCell Capsule is based, as many other product of the same series, on the ASR6051 chip, which integrates a 24 MHz ARM Cortex M0+ Core and a SX1262 Lora modem, allowing the system to achieve an ultra low power consumption in deep sleep state s (3.5 uA). Easily check which versions of mac OS, iOS, iPadOS, or watchOS are compatible with your Mac model or iDevice. Guide includes OS X 10.8.x to macOS 11.0.x.
Introduction
Before we begin, please make sure you've followed the steps from this guide,which goes over some initial setup steps.
This guide will walk through installing PlatformIO and deploying a HeliumArduino program on a target device.
PlatformIO is a cross-platform, cross-architecture,multiple framework, professional tool for embedded systems engineers and forsoftware developers who write applications for embedded products.
Here, we will detail the steps required to integrate a specific board type, oneof the Heltec CubeCell AB0xfamily of boards.
However, this guide can be also used to on-board many other types of targetdevices. In most cases one can just substitute your target device in place ofthe CubeCell developer board.
Objective and Requirements
In this guide, you will learn:
- How to setup your PlatformIO IDE environment
- How to create, build, upload a simple embedded application
- How to program a basic application that will send packets over the HeliumNetwork
- Verify real-time packets sent to the Helium Console via Hotspot that's inrange
For this example, you will need one of the following Heltec development boards.The Helium community has experience with the AB01, AB02x and CubeCell Capsuleline boards. Subsequent follow on products may work but have not been tested
Hardware
- Micro USB Type B Cable -Example
Software
Untitled mar game 2 mac os. PlatformIO is not a standalone IDE, it installs as an extension to MicrosoftVSCode. The Helium Console is a cloud based device management tool that we willuse to enable our device access to the Helium network. There is no installationrequired however one will need to create a user account with the Helium Console.
- VSCode (IDE)
Hardware Setup
Attaching the LoRa Antenna
Your board should have come with a U.FL antenna. All you have to do is attach itto the U.FL port on the developer board. The method of attachment variesdepending on the target board.
Vidya futura mac os. In the case of our example Heltec CubeCell board, some versions of the board mayhave more than one U.FL port, if this is the case generally the LoRa antennaattaches to the port that is on the same side of the board as contains the USBport connector. In all cases it is best to verify the proper connector with theboard manufacturer.
Connect Target Board to Development PC
The target boards are typically connected to the host computer via a USB 2.0A-Male to Micro B cable. Again this may vary depending upon your target board.
Install Develop Machine Serial Driver
Some operating systems, especially Windows, will require the installation ofhardware specific USB device driver code. Most hardware developer board vendorswill supply directions on how this can be accomplished.
For our example installation directions can be found on Heltec's documentationwebsitehere.
Software Setup
Setting up the VSCode/PlatformIO IDE environment while not complex, does requireseveral steps that are independent of your target device. We will walk throughthese initial setup steps before trying to integrate Helium network access codeinto the mix.
Installing PlatformIO
Using the VSCode instructions found heredownload and install Microsoft's Visual Studio Code. PlatformIO IDE is built ontop of VSCode as an extension. Once the VSCode is installed:
- Open VSCode Extension Manager by clicking on the Extensions icon on the leftside of the main view.
- Within the Extensions Marketplace search for official PlatformIO IDEextension
- Install PlatformIO IDE.(https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide)
It is highly recommended to give the quick-start guide a read. It will help younavigate the unfamiliar interface.https://docs.platformio.org/en/latest/integration/ide/vscode.html#quick-start
In this tutorial, as an example, we will be using theHeltec CubeCell AB0x. Onecan substitute your target device as needed as you progress through these steps.
Once PlatformIO is installed, you should be welcomed to VSCode with thefollowing 'PIO Home' screen:
If not already open, the PlatformIO 'Home' view can be opened by clicking on thehouse icon within the VScode status bar.
Creating a New PlatformIO Project
If you have not have not already used PlatformIO to build, upload and verify theoperation of a sample application it is best familiarize yourself with the basicuse of PlatformIO before adding the complexity of Helium network access code tothe mix.
If you are familiar and confident with the steps required you can continue at'Sample Helium Network Access Code' by clickinghere.
The following steps will walk you through what is required to:
- create a template project
- inspect the default source file, main.cpp as well as the primary projectconfiguration file, platformio.ini
- build the project and inspect the build log output
- upload the sample binary to the target development board.
- inspect serial output debug information.
Before proceeding with actual code that will connect to the Helium network,create a sample, template project.
Open 'New Project Wizard' - Select project name and board
- Within the 'PIO Home' view click on 'New Project'.
- At the 'Project Wizard' dialog enter a name for your project in the 'Name'field.
- Within the 'Board' field select the appropriate target board by entering thename of the manufacturer, 'Heltec' for our example. The PlatformIO auto searchfeature should present you with a known list of supported boards. In our casewe enter 'Heltec' and choose the 'Heltec CubceCell-GPS (HTCC-AB02S)' from thesupplied list.
Note: If your target device is different start to enter the device manufacturerin the 'Board' field, PlatformIO will attempt to fill in the entry with thosedevices that it is aware of. Hopefully your device will be presented in thelist. If so, select it.
Select framework and project location
- Select the desired runtime framework from the 'Framework' drop down. Targetdevices may support one, and possibly more than one, runtime framework. Choosewhat is appropriate for your target. At present only 'Arduino' is supportedfor the board we have selected for our example.
- For location, if the checkbox is selected the project will be created withinthe default PlatformIO workspace, which is sufficient for our purposes.
- Click the 'Finish' button to create the project. ( You may need to scroll downthe wizard window to expose the Finish button)
Note: The time taken to create a project will vary depending on whether or notthe selected platform and framework files have been previously downloaded. Whenthe project has been created it should be shown within the PlatformIO Explorerview typically found on the left side of the IDE.
Typical project explorer view.
Default project main.cpp
If you are familiar developing within the Arduino IDE, main.cpp is much the sameas the Arduino *.ino. It also contains default setup() and loop() functions.
PlatformIO also adds a required '#include <Arduino.h>' statement. This is animportant/necessary difference between PlatformIO and Arduino IDEs.
platformio.ini - project configurations
Let's take a look at the platformio.ini file in the root of our new project.This is where one defines project configuration definitions. In the Arduinoworld one would do this via the IDE tool bar selections.
Note: when this file is modified the entire project will be rebuilt when theproject is next built or uploaded.
Here we see the platformio.ini file that was created as a result of the runningthe New Project wizard targeting our CubeCell board.
Build the target device application
Now that the template project has been created it's time to build the deviceapplication. Within PlatformIO the 'Build' button is the check-mark found withinthe bottom status bar. Clicking on this button should start the build process.
Inspect the build output
Due to the defines within platformio.ini, PlatformIO is able to determine theproject board and framework dependencies. Any missing dependencies areautomatically installed at build time, thus this process may be seen in thebuild output. This feature allows us to add libraries into our platformio.inifile, which will then be downloaded for us, if needed, at build time.
The build process results can be found within the 'Terminal View' typicallyfound at the bottom of the VSCode window. Much like with Arduino, the buildoutput will dump the calculated amount of Ram and Flash memory used by yourapplication.
Start of the build output displaying configuration information.
Tail end of build log showing Ram and Flash usage. There is also a Problemsoutput view that may help when trying to resolve build issues.
List of attached devices
If, within the 'PIO Home' view, you select the 'Devices' icon on the left, youwill see listed any attached physical devices as well as their associated commports:
The list should reflect your target device.
Uploading binary to target device
Now that the code has built successfully, if a target device is attached to yourcomputer the resulting binary can be uploaded to the target device.
The method of uploading the binary to your device may vary depending on thetarget device. PlatformIO will attempt to configure upload options appropriatefor the chosen board. If the default configuration does not work in yourinstance detailed information can be found within the PlatformIO documentationhereor within your target board vendors documentation set.
We will attempt to include such information along with any sample project codewe provided if the procedure is different from that described here.
Click on the Upload button within the bottom Status bar.
Below you will see a typical output as the binary is uploaded to the targetboard.
If you have made it this far then we know your environment can build and uploada device application. Now it's time to connect to the Helium network.
Helium Console - Create Device
In order for a target device to communicate via the Helium Network a useraccount must first be created. Once the user account is created then a consoledevice must be created.
When creating the console device, make note of the DevEUI, AppEUI, and AppKeydevice credentials. These are used to connect to the network and will need to beinserted into the device application code below. A console quick start guide canbe found here.
Sample Helium Network Access Code
If you have not created a simple template project and you want to a try one ofthe samples you can copy a sample into your workspace where it should buildwithout error. A full PlatformIO project can be foundhere.Alternatively you can update the template project created above by continuingthe following steps.
Update main.cpp
Now that we have the required board and library runtime support installed, let'sprogram the board with an example Helium network enabled application.
To update the sample application created above:
- open, within PlatformIO, your projects src/main.ccp file
- replace this template main.cpp with the content of the sample applicationfoundhere.Copy and paste the entirety of it.
Add device credentials
Next we'll need replace the placeholder AppEUI, DevEUI, and AppKey values foundwithin the sample program with the real values found on the target device pagewithin the Helium Console.
For our CubeCell example all values are big endian (msb), most significant biton the left.
At the top of the main.cpp file, replace the three FILL_ME_IN fields, withthe matching field from the Helium Console, example shown below. Your numberswill be different depending on what the console creates when you add your targetdevice.
Verify LoRaWAN channels mask
Runtime library implementations are designed to work across several LoRaWANregions and networks. The firmware will attempt to join the network usingvarious frequency sub-bands, defined by a channel mask, until the join succeeds.It is recommended that you change the default channel mask to a value that willhelp the join process complete connection to the Helium network in a more timelymanner. The process, where and how, to update this channel mask will varydepending on the LoRaWAN runtime implementation
For our example using the Heltec CubeCell and it's runtime the following pieceof code has been incorporated into the sample projects. Refer to a sample todetermine where this code should reside, generally near the above mentionedcredentials is fine.
platformio.ini - project configurations
For our sample application we need a few configuration items added to theproject platformio.ini file. One set is the project defaults, the next is serialdebug monitor configurations and then LoRaWAN configurations.
Complete documentation of platformio.ini content can be foundhere. Serialdebug monitor specific itemshere.
Note: The comment character for this file type is the semicolon.
For our example CubeCell project we update the projects platformio.ini with thecontent from the sample project:
- open, within PlatformIO, your projects platformio.ini file
- replace this template file with the content foundhere.Copy and paste the entirety of it.
Once you have become more familiar with the LoRaWAN/Helium network feel free toexperiment with different configuration settings possible within platformio.ini.
Build the device application
After updating the main.cpp and platformio.ini files it's time to build thedevice application. Within PlatformIO the 'Build' button is the check-mark foundwithin the bottom status bar. Clicking on this button should start the buildprocess.
Inspect the build results
The build output results can be found within the 'Terminal View' typically foundat the bottom of the VSCode window. Verify the build completed successfully.
Possible Arduino to PlatformIO porting issues
When porting Arduino sketches to PlatformIO you may find errors such asundefined functions. These may be functions that are called by setup() or loop()or other custom functions prior to them being defined. This is a side effect ofthe different C version of C compilers used with PlatformIO vs Arduino. In thisinstance we just need to define the function prototype before the function isactually called. Another compatibility issue is that unlike Arduino IDE, youmust include Arduino.h at the start of your C file if you are using Arduinodefined constructs. Generally the compatibility issues are minor.
Verify Heltec runtime configurations.
Running the previous build operation will ensure the Heltec runtime dependencieshave been downloaded. At the time of this writing some versions of Heltec'sruntime libraries have set default configuration variables to values that areincompatible with the Helium network, especially when the Heltec device isconfigured targeting the North American market. Please follow thislink within this document and verify the filecontent. Return here after verification.
If changes needed to be made it is best to run a 'Clean' build process byclicking on the Trash Can button on the status bar followed by a 'Build' toensure the changes have been picked up properly.
Cube Cell Mac Os Download
Upload Binary to target device
If the build process completed successfully, upload the binary to the targetdevice via the 'Upload' (right pointing arrow) button found on the status bar
NOTE: Prior to attempting to upload your binary make sure any terminal sessionthat might be attached to the debug comm port has been deleted. Occasionally butnot always, PlatformIO will automatically close the comm port, if it does notupload errors will occur.
Successful upload example, your results will vary.
Viewing Target Device Serial Output
When your firmware update completes, the board will reset, and begin by joiningthe network. The PlatformIO Serial Monitor can be used to view the serial debugoutput from the board. You will recall that we set the serial portconfigurations within the platformio.ini file for our project.
To open the serial monitor click on the 'Serial Monitor' button within thestatus bar.
You should begin to see output similar to below.
You can use any virtual terminal emulator for this purpose, but recall certainHeltec boards seem to require the terminal emulator be disconnected from thetarget device prior to attempting to upload a new binary.
Helium Console Uplinks
Now let's head back to the Helium Console andlogin to your account. Once logged in select the 'Devices' item on the left,then select the target device previously created. Scroll down a bit on thedevice page and you should see something similar to the screenshot below.
Activation messages are those seen when the device first attempts to join thenetwork.
Downlink messages are those delivered from the network to your target device.
Uplink messages are those messages delivered from your target device to theHelium network.
Downlink messages are those delivered from the network to your target device.
Uplink messages are those messages delivered from your target device to theHelium network.
Congratulations! You have just transmitted data on the Helium network! The nextstep is to learn how to use your device data to build applications, visit ourIntegrations docs here.
Device Application Code Debugging
Unfortunately at this time CubeCell does not support a debug probe that enjoysbuilt-in support within PlatformIO. Please visit the Heltec community forumfound here for help with external debuggerquestions.
Misc device application hints
Follow this link within this guide for usefulapplication enhancements.
Manual updates to the Heltec runtime libraries
Some versions of Heltec's runtime libraries have set default configurationvariables to values that are incompatible with the Helium network, especiallywhen the Heltec device is configured targeting the North American market. Thefollowing discusses Heltec runtime files that must be inspected to ensurecompatibility. The exact location of these files will depend on which operatingsystem you are using, Windows, Linux, or Mac. The typical top level location ofthe runtime libraries is shown below for each operating system. From there thefollowing discussions will present to you the file locations within these toplevel directories/folders. Please note the Heltec library version numbers areexpected to change as time goes on. XXXXX denotes your specific user id.
PlatformIO IDE Heltec runtime library locations:
Verify LoRaWAN Data Rate
Within an editor of your choice open the file path formed by prepending theabove described platform specific top level directory structure to the followingfile:
Within this file look for
Depending on the version of the Heltec runtime that is installed this defaultmay be set to DR_0, DR_3, DR_5 or some other value. Note: DR_5 is not valid forUS915, the North American market.
The defaultDrForNoAdr setting is tied directly to the maximum size of the datapacket you are transferring.
NOTE: If you try to transfer a packet that is larger than this setting allows,your device may successfully join the network but the data transmit will failsilently.
Data Rate (DR) | Max Application Payload |
---|---|
DR_0 | 11 bytes |
DR_1 | 53 bytes |
DR_2 | 125 bytes |
DR_3 | 242 bytes |
DR_4 | 242 bytes |
DR_5 - 7 | Not Valid |
Update the defaultDrForNoAdr as appropriate for your application needs.
The above values are valid for the US902-928MHz region(North America), thevalues may differ for other LoRa regions, which you can findhere.
Dynamic Data Rate Change
If your application needs to change the current uplink data rate dynamically andAdaptive Data Rate (ADR) is not enabled, one can call the
API within your sketch. If you do call this API it must be called after theLoRaWAN.init() within your sketch for the change to be effective.
Verify LoRaWAN preamble size
Cube Cell Mac Os 11
There are some versions of the Heltec runtime libraries that may set a LoRaWANpreamble size that is incompatible with the current LoRaWan specification. Ifthe preamble size is not set correctly your device cannot join the network. Thisshould be verified in the region specific file corresponding to the region yourdevice is targeting. Be sure to prepend the above described platform/IDEspecific top level directory structure.
The following is the file that must be checked if targeting region US915. Withinan editor of your choice open the file path formed by prepending the abovedescribed IDE/platform specific top level directory structure to the followingfile:
Within this file locate the line below, the 7th parameter which might be 14should be changed to either 8 or 16. Either value will work. Earlier versions ofthe runtime may have this value set to 14 which is 'not' correct. Change:
To:
Heltec support has been notified of these issues, hopefully a future release ofthose libs will resolve the issues.
Patching ADR Functionality
The CubeCell may have issues joining the network with ADR OFF. If you're usingADR ON, you may also encounter an issue where your CubeCell stops successfullysending packets after a few minutes. This is caused by the CubeCell firmware'sADR behavior, and may happen if your payload is above the DR0 maximum size (11bytes).
To patch the CubeCell firmware, find and open the
RegionUS915.c
in thefollowing location.Find the following lines in the file and comment them out:
This will prevent the CubeCell from reducing the Data Rate over time and allowyou to send larger packets on a repeated, prolonged basis.
Device application hints
Using HTCC-AB02S Board with GPS Capable Sketch
Cube Cell Mac Os X
If you are using the HTCC-AB02S board with a program that is GPS enabled butfind the device is unable to obtain a GPS lock you can try changing the GPS datasatellite source via the GPS class Air530.setMode() API. Add theAir530.setmode() to the setup() method of your sketch.
A sample GPS enabled project for the CubeCell can be foundhere.
Dynamically altering Data Rate
A recent change to the Heltec runtime exposes an API interface a deviceapplication can use to alter the current LoRaWAN data rate.
This should be done sometime after LoRaWAN.init() is called.
By @bluejedi:
This is the main topic for the new Heltec CubeCell Series products.
The CubeCell products are based on the ASR650x series SiP (system-in-package) which combine a Cypress PSoC 4000 ARM Cortex-M0+ 32 bits 48MHz MCU (with 16kB SRAM and 128kB flash) together with a Semtech SX1262 LoRa tranceiver in a single package.
The CubeCell products are based on the ASR650x series SiP (system-in-package) which combine a Cypress PSoC 4000 ARM Cortex-M0+ 32 bits 48MHz MCU (with 16kB SRAM and 128kB flash) together with a Semtech SX1262 LoRa tranceiver in a single package.
The CubeCell modules have an integrated LoRaWAN stack (based on Semtech’s LoRaMac-node). It can be programmed via API and also via serial AT commands.
The CubeCell products support development with the Arduino framework. Sketches are uploaded via the serial port. The development boards have a USB port with USB-to-serial so sketches can be easily uploaded via USB. Uploading sketches to the sensor capsules requires a special adapter from Heltec.
The CubeCell development boards and sensor capsules come in different shapes with different optional features like UFL/IPEX or SMA antenna connector, RGB LED, OLED display, battery holder, GPS and solar panel (connection).
For an actual overview of available CubeCell products, links to product documentation, GitHub repository and PlatformIO documentation see Part 2 of this topic:
For the next part of this topic see: Heltec CubeCell - part 2
Original post by @rodri16 :
Hi, there is a new board from Heltec called CubeCell, Arduino compatible.
https://heltec.org/cubecell/
What do you think?
https://heltec.org/cubecell/
What do you think?