This new logger board was developed by the Stroud Water Research center with funding from the USGS's NGWOS External R&D Program. The brain of the new board is a Microchip Technology's ATSAMD51N19A.

• The EnviroDIY Stonefly
  • Downloading files from GitHub
  • Setting up the Stonefly in the Arduino IDE
    • Installing or Updating Libraries for the Examples in the Arduino IDE
  • Setting up the Stonefly in PlatformIO on VSCode
    • Installing Libraries for the Examples in PlatformIO
    • Enabling intellisense for ino files
  • Example Programs
  • UF2 bootloader
  • Reprogramming a Sleeping Logger

To use these examples, you must to be able download and save files from GitHub and move them to the correct folder on your computer. The individual instructions for setting up your board, setting up your libraries, and setting up each example will tell you which files you need to download for each. There are several ways you can download files from GitHub:

• Download one file at a time using the download button for each file.
  • Navigate to each file you're interested in and download that file using the download button. This will save files to your browsers download folder.
  • 
• Save the raw content of each text-like file one at a time to a file on your computer.
  • Go to the file you want to download.
  • Click it to view the contents within the GitHub UI.
  • In the top right, right click the Raw button.
  • Select Save as... and save the file somewhere on your computer.
  • 
  • Alternately, left click the Raw button, then when the raw text opens, right click on the page and select Save as....
• Download whole folders as zip files using the link helpers in each example ReadMe.
  • These links use a secondary download helper page, so - while unlikely - your browser may complain if you have security settings at max.
  • After downloading the folder, unzip (decompress) the files and move them to the appropriate location on your computer.
• Download the entire repository as a zip file and move files as you need them to the appropriate location on your computer.
  • 
• Clone the repository (git users only)
  • If you don't already know how to do this, you do not need to.

To use the Stonefly in the Arduino IDE, you must be using at least version 2 of the IDE. The IDE can be downloaded here. These instructions were testing using version 2.3.4 of the IDE. You must have administrator privileges on a Windows computer to install the Arduino IDE and the Adafruit SAMD core needed by the Stonefly.

To add the EnviroDIY Stonefly board to your Arduino IDE, go to File > Preferences (for a Mac: Arduino > Preferences) and copy the following URLs into the box labeled "Additional Boards Manager URLs":

https://raw.githubusercontent.com/EnviroDIY/Arduino_boards/master/package_EnviroDIY_index.json,https://adafruit.github.io/arduino-board-index/package_adafruit_index.json

If you already have other custom board manager URL's, extend your list with the EnviroDIY link, separating the URLs with commas.

Then in the IDE, click on Tools > Board > Boards Manager. Use the dropdown box for Type to select "Contributed". You should then see an option for "EnviroDIY SAMD Boards". Click the "Install" button to add the EnviroDIY boards to your IDE. The install process should also install the Adafruit core into the Arduino IDE. As mentioned above, you must have administrator privileges on a Windows computer for the install to succeed. If you have problems installing the board and core in the board manager, Adafruit has more detailed instructions here. When following the Adafruit instructions, make sure to use both the EnviroDIY URL above and Adafruit's URL.

Once the board and core packages are installed, when you click Tools > Board you will see EnviroDIY SAMD boards > EnviroDIY Stonefly listed as options for available boards.

The examples in this repository require a large number of Arduino libraries to compile. Managing library dependencies using the Arduino IDE can be tricky as the Arduino IDE does not support any sort of virtual environments for different sketches. The correct version of all of the dependencies for all of the examples are in this zip file.

To install all of the libraries, download the zip file and un-zip it. The result of the unzipping should be a bunch of sub-directories. Move all of the sub-directories from the unzipped directory into your Arduino libraries folder. Instructions for finding your libraries folder are here. The final folder structure should be have one subfolder of your libraries folder for each library. You should not have a single "AllDependencies" folder in your libraries folder. You also should not have any bare files in your libraries folder, only folders.

A correct example (using the default Windows folder location):

C:\Users\{your_user_name}\Documents\Arduino\libraries
    └ Adafruit ADS1x15
      └ ... library files ...
    ... lots more libraries in folders ...
    └ Yosemitech Modbus
      └ src
        └ ... library files ...

PlatformIO is both an command line interface and extension for Microsoft Visual Studio Code for embedded software development - including Arduino programming. It is more powerful - and less beginner friendly - than the Arduino IDE. For those unfamiliar with programming, the Arduino IDE is easier to start with. For those who do other programming, want intellisense, compiling, and linting options, or want library and environment management, PlatformIO is the way to go.

To use the Stonefly in PlatformIO, you must manually download the boards and variants files and put them in the correct folder.

• Navigate to your PlatformIO core directory. On Windows, it will be something like C:\Users\{yourUserName}\.platformio.
• If they don't already exist, create a "boards" folder and a "variants" folder within the PlatformIO core directory.
• Download the Stonefly boards file here and put it into your new boards subdirectory.
  • On windows, the new file should end up being C:\Users\{yourUserName}\.platformio\boards\envirodiy_stonefly_m4.json
• Download the stonefly_m4 folder in this variants directory and all of the files from the folder and put that folder and all of its contents in your new variants folder.
  • You should end up with these files:
    • C:\Users\{yourUserName}\.platformio\variants\stonefly_m4\pins_arduino.h
    • C:\Users\{yourUserName}\.platformio\variants\stonefly_m4\variant.h
    • C:\Users\{yourUserName}\.platformio\variants\stonefly_m4\variant.cpp
    • C:\Users\{yourUserName}\.platformio\variants\stonefly_m4\linker_scripts\gcc\flash_with_bootloader.ld
    • C:\Users\{yourUserName}\.platformio\variants\stonefly_m4\linker_scripts\gcc\flash_without_bootloader.ld
• Create a new PlatformIO project through PlatformIO home. If you have correctly added envirodiy_stonefly_m4.json to your boards folder, you should see the option for the Stonefly in the board selection dropdown.
• You must modify your platformio.ini file to specify the location of your variants folder. Your Stonefly environment should look like the code below.
  • NOTE: You do NOT need to replace ${platformio.core_dir} with your real core directory. Leave that exactly as is in your ini.

[env:envirodiy_stonefly_m4]
platform = atmelsam
board = envirodiy_stonefly_m4
framework = arduino
board_build.variant = stonefly_m4
board_build.variants_dir = ${platformio.core_dir}/variants
board_build.ldscript = ${platformio.core_dir}
/variants/stonefly_m4/linker_scripts/gcc/flash_with_bootloader.ld

Managing libraries in PlatformIO is much easier because of the package manager. You should be able to get all the correct versions of dependencies by using the platformio_example.ino file (after renaming the file to platformio.ini).

By default, VSCode and PlatformIO do not treat Arduino ino files as c++ (cpp) files. To forcibly enable cpp intellisense for the ino files:

• Open "Settings" using the 'gear' icon, command pallet, or ctrl+, keyboard shortcut.
• Search for files.associations in the settings search bar
• Within the file associations setting add a new item with the key *.ino and the value cpp.

There is more information in the PlatformIO documentation about the conversion of ino files to cpp files. ALL ino files within this repository are already valid cpp files; they are named as ino files only for the Arduino IDE.

This repo contains these example programs for the USGS:

• Programs for Amazon Web Services / IoT Core and the training workshop

  • NGWOS_AWS_MQTT_CERTS
    • This program is used to upload the required certificates for AWS IoT Core to the modem module.
  • NGWOS_AWS_MQTT
    • This program transmits data from a VEGAPULS C 21 and onboard sensors from a Stonefly data logger to AWS IoT Core's MQTT server using cellular data. It also saves images from a Geolux HydroCam to a SD Card and transmits them to AWS S3.
  • NGWOS_AWS_LORA
    • This program transmits data from a VEGAPULS C 21 and onboard sensors from a Stonefly data logger to a LoRa gateway for further forwarding to AWS IoT Core. It also saves images from a Geolux HydroCam to a SD Card.

• Out-Dated and un-used testing programs:

  • NGWOS_TTN
    • This program transmits data from a VEGAPULS C 21 and onboard sensors from a Stonefly data logger to The Things Network
  • NGWOS_VegaAndHydroCam
    • This program transmits data from a VEGAPULS C 21 and onboard sensors from a Stonefly data logger to Monitor My Watershed. It also saves images from a Geolux HydroCam.
  • NGWOS_Hydros21_HydroCam
    • This is identical to the Vega and HydroCam example, but with a Meter Hydros21 instead of a Vega Puls.
  • NGWOS_AWS_WIFI_Certs
    • This program is identical to NGWOS_AWS_MQTT_CERTS but uses an ESP32 Wi-Fi module instead of a cellular module.
  • NGWOS_AWS_WIFI
    • This program is identical to NGWOS_AWS_MQTT but uses an ESP32 Wi-Fi module instead of a cellular module.

Follow the steps above for installing the libraries for either the Arduino IDE or PlatformIO.

Detailed instructions for each example are in the ReadMe files in the respective sub-folders.

The bootloader we are using on the board is Adafruit's fork of Microsoft's UF2 bootloader. Adafruit has more information on the bootloader here. The bootloader was built with help of a python toolchain, forked here. The final bootloader files are available on GitHub here. There are detailed instructions for reinstalling the bootloader here, but there generally shouldn't be any reason to reinstall it. You must have a special programmer or debugger board to install the bootloader.

The on-board USB used to program the logger shuts down when the logger goes to sleep. This creates issues because the IDE cannot find the logger to program it when the board is sleeping - which it's doing most of the time while running a logger program.

To program a sleeping board:

• watch the output from the upload on the Arduino IDE
• when you see the line "Waiting for upload port", quickly double-tap the reset button on the logger to get it to wait and enter bootloader mode where it can receive the program

When the IDE attempts to upload the board, it assumes the board is in "running" mode, sends a command to the board to tell it to go to "programming" mode and then waits until a new port appears. The sleeping logger isn't in running mode and doesn't hear the command, so you have to do it manually. BUT, if you put the board into programming mode in advance, the IDE detects the board, thinks it's "running" and then errors out when the already-in-programming-mode board responds incorrectly to the "go to programming" command. The upload will also error out if it takes too long for the bootloader port to appear. So you have to watch and wait and hit the double tap just at the right time. It's kind of a PITA.