Tutorial

Steps you will take

• Arduino IDE
• Northern Widget board definitions
• ATTinyCore microcontroller definitions
• Third-party microcontroller definitions (if needed for sensors)
• Northern Widget libraries and dependencies
• Clock-setting GUI

Helpful external Arduino tutorials and documentation

We use Arduino because it is a popular system with a large user base, mature software libraries, and extensive support! The information here is tailored a bit more to our sensors and data loggers, but is not as extensive as help available elsewhere on the internet. Here are some curated links to guides:

Adafruit: Learn Arduino

• Lesson 0
• Lesson 1
• Lesson 2

Official Arduino programming reference

Adafruit: Adding Third-Party Boards

Arduino software, libraries, and boards definitions

Arduino is an open-source electronic hardware development platform. For more information on Arduino, go to https://www.arduino.cc/.

Download and install the Arduino IDE

The Arduino IDE (Integrated Development Environment) is the current programming environment we use to write and upload programs to the Northern Widget sensors and data loggers. (Other options exist, but this is the most beginner-friendly.) We haven’t yet tested the brand-new web editor, so we’ll be suggesting an old-fashioned download. And if you’re deploying these in the field, you’ll need the downloaded version! To download, go to https://www.arduino.cc/en/Main/Software.

Note: For Windows users, go for the standard download, not the “app”.

Set up the Northern Widget board definitions

Note: This step is required only if you are using a Northern Widget data logger (Margay or Okapi). You may skip this step if you are using a standard Arduino or other board for which you already have support through the Arduino IDE.

The Northern Widget boards are third-party Arduino boards, so you’ll have to set up support for these boards yourself. We’ve made a pretty thorough walkthrough that you can view here at https://github.com/NorthernWidget/Arduino_Boards.

Add board definitions for the ATTinyCore microcontrollers

Note: This step is required only if you have to upload firmware to Northern Widget sensors.

You can follow the instructions to download and install ATTinyCore microcontroller support in the Arduino IDE, but for clarity here are some basic instructions:

• Go to the ATTinyCore microcontroller GitHub page, here you will find all details about ATTinyCore
• Scroll down and click on the “Installation” link right above the “Wiring and required components link”
• From there, follow the installation instructions based on your preferred installation method - either through the Arduino Boards Manager or manually

Install all Northern Widget libraries and their dependencies

We have a set of custom firmware libraries designed to make your life easier. The only step that you have to take is to install them. Go to https://github.com/NorthernWidget/NorthernWidget-libraries and follow the instructions in the README to add these to your libraries folder.

Install the graphical user interface (GUI) to set the logger’s clock

Follow the instructions on the SetTimeGUI GitHub page.

Materials needed:

• Your PC with the software/libraries loaded listed in Step 1:
• Arduino-compatible device (e.g. your logger)
• A programming cable, which can be:
• An in-system programmer (ISP) that attaches to a 6-pin header on the board

Note: If you are just programming an Arduino board or data logger, which already has a bootloader installed (if you don’t know what this is, it probably has it), then all you need is your PC, the board and the USB cable.

The basics of uploading programs

Arduino programs, often called “sketches”, are how you tell an Arduino device what to do. Here is some information to get you started.

Terminology

• Microcontroller: A computer chip that integrates a processor, memory, and methods to take electrical inputs and send electrical signals.
• Software: A program that involves active changes and interactions. This typically exists on a computer and runs within an operating system. An example here is the Arduino IDE.
• Firmware: A program that is uploaded once to a computer or microcontroller and then executes the same set of commands. Any code that you upload to an Arduino-compatible device is an example of firmware.
• Sketch: The Arduino name for the C++ source code in which you write a program.
• Bootloader: A small piece of firmware that is installed in a specific portion of the microcontroller’s memory. In the case of Arduino-compatible devices, this is almost always to allow the device to be programmed via USB.
• Function: A defined section of code that completes some task and optionally returns output.
• Class: A container that holds functions and variables. An object is a particular instance of a class (e.g., the class is Cap’n Crunch (or pick another cereal or item); my box of Cap’n Crunch is an object).
• Library: A piece of pre-written code that you can #include within a program (such as an Arduino sketch) in order to use its functions. This typically helps to shorten the length of your sketches by hiding a lot of complicated code and exposing it as functions that can be called in just a single line of code. It contains a *.h and a *.cpp file and typically resides within the “libraries” folder of your Arduino app (in the case of Mac) or directory (in the case of Linux or Windows).

Arduino starting screen

When you open the Arduino IDE, you will see a default blank “sketch”:

voidsetup(){// put your setup code here, to run once:}voidloop(){// put your main code here, to run repeatedly:}

setup() and loop() are both functions. These are specific sets of code that are executed when their names are called in the code. These two functions are special in that:

1. Every Arduino program must have them.
2. They do not need to be called by code that you write: Arduino automatically interprets and, indeed, requires that these be included.

In addition:

• You may include other code libraries and declare variables before these functions.
• You may include additional functions after these functions.

Bootloading

Note: If you are just programming an Arduino board or data logger, which already has a bootloader installed (if you don’t know what this is, it probably has it), then please proceed to the “Uploading code to the Arduino-compatible device” section below.

In-system programmer

Important note for Linux users: You must supply permissions to the Arduino IDE for it to be able to use the ICSP, or you will have to run it using sudo. The former option is better; the latter is easier in the moment.

In order to bootload your logger or sensor you will need to use a special device called an “in-circuit system programmer” (or just “in-system programmer” or “ISP”) that attaches to a 2x3 header, with either 2.54 mm (0.1”) or 1.27 mm (0.05”) spacing. ISPs may be used in Northern Widget devices for:

• uploading a bootloader, or
• uploading firmware for a sensor.

Many devices exist to upload bootloaders or firmware, including:

• The official AVR ISP mkII (no longer produced but available used)
• Using an Arduino as an ISP
• The versatile Olimex AVR-ISP-MK2
• The Adafruit USBtinyISP

Note: Be sure to download and/or update drivers for your ISP.

In either case, you follow these two steps:

1. Plug your ISP of choice into your computer (via a USB cable) and plug the ISP into your device (via the 6-pin header). There are two ways to place it on; the header is aligned such that the ribbon cable should be facing away from the board while programming. If this fails without being able to upload, try flipping the header around. This should both power the board and provide communications.
2. Go to Tools –> Programmer and select the appropriate programmer based on what you are using.

To upload the bootloader, you go to Tools –> Burn Bootloader. If you are doing this on an Arduino or data-logger board, you may have to plug in the USB cable to supply enough power and to go to Tools –> Port and select the proper serial port for your device. (It is not programmed via the serial port though, so I (Wickert) do not understand why you sometimes have to do this.)

Lights should flash on the programmer and board and a message should appear in the Arduino IDE that tells you whether or not you have succeeded. If it fails, try these approaches in order:

1. Try flipping around the ISP (also called “ICSP”) attachment;
2. Make sure that all of your USB-cable connections are secure;
3. Double-check your drivers are up-to-date;
4. Double-check if administrator permissions are needed for the Arduino IDE, if so give them;
5. Desperate internet searching.

Uploading code to the Arduino-compatible device

Once your code is written – either as a copy/paste of this or as your own – save your code. All Arduino sketches need to be within their own folder; the Arduino IDE will ensure that this happens. After saving, you can upload in one of two ways:

If you upload the above code to an Arduino device, it will do nothing, because the code contains no instructions.

Uploading via USB

If you are programming the board via USB, hit the “upload” button (right arrow) to load the code to the board. (The check mark to the left will test if your code compiles.)

Upload the Arduino sketch to the board. (Pay no mind to the specific text; this comes from our old ALog data logger.)

Uploading via In-System Programmer (ISP)

If you are uploading firmware using the in-system programmer, you then go to Sketch –> Upload Using Programmer. After several seconds, you learn whether you succeeded or failed. Hopefully it worked!

Programming Northern Widget data loggers

Each of our data loggers’ README.md pages contains information on programming them, with (at the time of writing).

Important functions

The most important functions for our standardized sensor interface are:

• mySensorObject.begin(<variables if needed>): performs the work to start up the sensor and prepare it to take measurements
• mySensorObject.getHeader(): returns an Arduino String object containing an informational comma-separated header describing the sensor measurements and their units.
• mySensorObject.getString(<optional boolean in some cases to choose whether or not to update the values when taking a reading>): returns an Arduino String object containing comma-separated data from the sensor readings.

Programming reference

We use a combination of doxygen and moxygen to auto-generate documentation for our firmware libraries. These are currently available for:

• Okapi data logger
• Haar atmospheric temperature, pressure, and relative humidity sensor
• Walrus submersible pressure (water-level) and temperature sensor
• Symbiont LiDAR rangefinder and orientation sensor
• T9602 atmospheric temperature and relative-humidity sensor; the main README.md page for this third-party sensor contains more general information about using and programming it, so its reference documentation is in a separate Markdown file.

Troubleshooting

• Make sure your version of the Arduino IDE is up to date
• Make sure the libraries are correctly installed on your machine
• If your code compiles properly but still fails to successfully upload:

Setting the clock

Before you record data, you’ll want to make sure that your logger knows what time it is. This is the only way to ensure that your data are paired with the proper timestamp, without which they often become much less useful!

Follow the instructions and images on the SetTime GUI GitHub page, and/or watch the video below:

Margay library references

We use Doxygen to auto-generate basic code referencing information, and populate this into the Readme markdown files.

• Firmware library for Margay

Guide to Margay field operations and LED flash patterns

Margay field and LED flash interpretation guide. 

Let’s make these more intuitive and user-friendly

Data files and SD cards

• Proper ways to swap SD cards
• Copy/pasting data files
• Example data-file contents

Google Sheets and telemetry

• Log in to Google Sheets
• Note: output might all be in a single cell – not split by columns, depending on code used to return data

Recommended Tools

• Tool roll picture
• List with rationale

Example mounting structures

• Including information / pictures on attaching loggers and sensors to these structures

Example deployments

• Include photos, videos, descriptions, …, curated from multiple folks at multiple sites
• Possible ideas below

Stream gauge

Lake-level gauge?

Weather station

Glacier-ablation station