Helium Developer Kit and PlatformIO on Mac

As I have been excited and eager to begin developing on the Helium network, I decided that it was time to step away from the Arduino IDE. Arduino is simple and friendly(...sometimes), but it is great for starting out with IoT. My main reason for the switch is the lack of editing features that make more complex code hard to read, write, and debug. So as I began reading Helium's PlatformIO setup tutorial (which is most likely great for PC users), I noticed some differences in the instructions that did not match up for MacOS, and some 3rd party software that was necessary to install that was not available for Mac.

Getting Started

Download Visual Studio for Mac and install it. Once it is installed you can install the PlatformIO IDE.

If you have never used PlatformIO, like me prior to installing it the other day, I highly recommend a quick walkthrough from PlatformIO's docs website.

Starting a PlatformIO Project

Once you have installed VS Code and PIO (PlatformIO), open it up and you will see the home screen such as the one below.

To begin a new project, select the "New Project" button under the "Quick Access" column on the right-hand side. There will be a pop for you to enter the name of your project, the board you are using, and the framework. Choose a project name, and then select the following for the board and framework:

Click "Finish" to create the project.

It may take a few minutes to initialize, but after it completes, you will see some files pop-up on the left-hand side, such as the ones in the red box below:

If you open the "src" folder and click on the file "main.cpp", you will see the familiar Arduino IDE functions, voidsetup() and voidloop(). Here you will write code just like you would in the Arduino IDE.

Setting Up the Environment

Take a look at the "platform.ini" file, and you will see some variables listed as so:

The "platform.ini" file stores information about your board and how to build the code prior to uploading it. If you build the project with current variables (by clicking the checkmark in the red box on the bottom), PIO will analyze the platform we are trying to build on and install various dependencies that have not been met.

Up to this point, everything has been the same as the tutorial from the Helium Developer website, but here is where some things start to differ.

If you go back to the PIO homepage and click on "Devices", you will see a list of devices and the port they are connected to. This is what my "Devices" tab looks like (disregard the first two):

On the Helium developer tutorial, their devices show something slightly different:

Obviously, there is a difference between what PIO is showing for my devices and the Helium's devices. When I initially saw this I decided to continue following the instructions they gave and see where it took me. So I tried to flash the board and received a different error than what was expected based on their instructions:

Configuring upload protocol...
AVAILABLE: blackmagic, jlink, mbed, stlink
CURRENT: upload_protocol = stlink
Uploading .pio/build/disco_l072cz_lrwan1/firmware.elf
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
debug_level: 1

srst_only separate srst_nogate srst_open_drain connect_deassert_srst

target halted due to debug-request, current mode: Thread 
xPSR: 0xf1000000 pc: 0x08000d9c msp: 0x20005000
STM32L0: Enabling HSI16
** Programming Started **
Error: jtag status contains invalid mode value - communication failure
Error: error writing to flash at address 0x08000000 at offset 0x00000000
embedded:startup.tcl:449: Error: ** Programming Failed **
in procedure 'program' 
in procedure 'program_error' called at file "embedded:startup.tcl", line 508
at file "embedded:startup.tcl", line 449
*** [upload] Error 1
======================================================================= [FAILED] Took 6.10 seconds =======================================================================
The terminal process terminated with exit code: 1

Helium's error is only slightly different, but initially, I did not notice this difference and still continued on. At this point, Helium's tutorial describes the cause of the error they received was a result of PIO being set up to flash the board with a SEGGER JTAG interface, rather than the ST-LINK interface that is integrated into the board. So, I immediately thought that if PIO was recognizing my board with an ST-Link interface (as seen from my "Devices" picture) I should most likely stick with ST-Link as the upload protocol rather than trying to download the SEGGER software that upgrades the ST-Link onboard interface. Regardless, following the steps that are given by SEGGER's website to upgrade the ST-Link interface to a JLink did not work. It requires you to download the SEGGER STLinkReflash utility which is only available for Windows.

From here I had reached a dead end in terms of Helium's instructions, so I began to search for alternate solutions, and looked around for if anyone else had received these errors. Unfortunately, I did not find a solution or anyone discussing this issue with Macs. So I started to read the documentation on ST-Link and the ST Disco-L072CZ-LRWAN1 on the PIO docs and I realized that Mac's already have ST-Link drivers installed, which explains why PIO recognizes it on my computer and shows up as JLink based on Helium's guide. Therefore, I figured it would be best to just stick with ST-Link, seeing that I did not really have any other options anyway.

After digging around the internet, and trying various different methods to get this to work, I ended up with this "platform.ini" file:

; PlatformIO Project Configuration File
;
;   Build options: build flags, source filter
;   Upload options: custom upload port, speed and extra flags
;   Library options: dependencies, extra library storages
;   Advanced options: extra scripting
;
; Please visit documentation for the other options and examples
; https://docs.platformio.org/page/projectconf.html

[env:disco_l072cz_lrwan1]
platform = ststm32
board = disco_l072cz_lrwan1
framework = arduino
upload_protocol = stlink

; change microcontroller
board_build.mcu = stm32l072cz
; change MCU frequency
board_build.f_cpu = 32000000L

lib_extra_dirs = ~/Documents/Arduino/libraries

monitor_port = /dev/cu.usbmodem14103
monitor_speed = 115200

The upload_protocol,board_build.mcu, and board.build.f_cpu variables were taken from the board's PIO docs. Another tip for those new to PIO, is that to use the serial monitor, you must enter those two variables for it to popup in the monitor. To open the serial monitor, you click on the little plug, in the same row where the build and upload buttons are.

Finally, once you have the "platform.ini" set up, as shown above, you will most likely get the same error I received if you try to upload. The last trick is still a workaround and why it works, I am not sure. Once you hit upload, in the terminal you will begin to see it build, and eventually, yellow text will pop saying that is opening the OpenOCD debugger. As soon as you see the yellow text, hit the RESET button on the board. Then instead of getting the error shown above stating: "Error: jtag status contains invalid mode value - communication failure", you will see:

Configuring upload protocol...
AVAILABLE: blackmagic, jlink, mbed, stlink
CURRENT: upload_protocol = stlink
Uploading .pio/build/disco_l072cz_lrwan1/firmware.elf
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
debug_level: 1

srst_only separate srst_nogate srst_open_drain connect_deassert_srst

target halted due to debug-request, current mode: Thread 
xPSR: 0xf1000000 pc: 0x08000d9c msp: 0x20005000
STM32L0: Enabling HSI16
** Programming Started **
** Programming Finished **
** Verify Started **
** Verified OK **
** Resetting Target **
shutdown command invoked
======================================================================= [SUCCESS] Took 9.87 seconds =======================================================================

And that is all, the code has been uploaded to the board!

Sometimes, it may take a few tries of uploading to get the timing right, but if you keep trying it should work. In case you are having trouble, another method that worked for me was holding the reset button down and releasing it until I saw the yellow text.

Conclusion

As I said earlier, I do not really know why this works. After reading some of the documentation on the hardware involved, and based on the JTAG error, I believe there is some sort of miscommunication between the ST-Link debugger and the JTAG connection, specifically on being able to reset the board. If you took a look at the ST-Link docs, you may have noticed the JTAG diagram which shows that it contains a reset pin. While I am no expert on this low-level hardware, that seems to be my hunch, since manually resetting the board seems to allow it to flash the board. Finally, I hope this helps some of my fellow Mac users out there trying to get through this issue and start developing on Helium!