Install a new sensor

Before you start

This walk-through takes a new EnviroDIY Mayfly from a box on the bench to a sensor that uploads its own readings. It is the device-push path described in Adding sensors: the Mayfly posts each reading straight to the Geronimo IoT upload API, so nothing on the server polls it. You need an active account with permission to create sensors, the Mayfly, a USB cable, and a computer with the Arduino IDE. If your device is not a Mayfly, the same three steps apply — only the firmware differs, and the API documentation describes the request it has to make.

Step 1: Configure the server

First, create the sensor's entry on the server. This is what tells Geronimo IoT to accept uploads for it and issues the credential the device will use.

1. Open Add a New Sensor (or go to the Sensors list and press + Add a New Sensor).
2. Give it a Site Code and set Data Source to Geronimo IoT API. The upload frequency and timezone fields disappear — the device controls both.
3. Expand Downtime alerts and set a Downtime threshold (minutes), so you are told when the device stops reporting. A push sensor has no polling interval to derive one from.
4. Press Save Sensor.

Note the sensor's storage key (shown under its name on the Settings page; for a new sensor it is the site code as typed). That is the sensor_id the device identifies itself with.

Step 2: Program your device

Next, program the Mayfly. You can use the pre-made Arduino sketch from the repository below or write your own against the API documentation. Please request approval before uploading faster than once every five minutes; uploads are also rate-limited per credential (600 requests per hour by default), so a device that reports often should batch its readings.

Download prerequisites

• Install the Arduino IDE.
• Download the code and libraries from the Strawberry Creek Monitoring Group's may-fly-code repository — a third-party account, not one this platform publishes or controls; read what you flash. This includes Mayfly_Code_CustomAPI.ino, StrawberryCreekPublisher.h and the custom libraries.

Configure the Arduino IDE for the Mayfly board

• Open the Arduino IDE and go to File > Preferences.
• In Additional Board Manager URLs, paste https://raw.githubusercontent.com/EnviroDIY/Arduino_boards/master/package_EnviroDIY_index.json.
• Go to Tools > Board > Boards Manager..., search for "EnviroDIY" and install it.

Install the custom libraries

• In the Arduino IDE, find your sketchbook location under File > Preferences.
• Open that folder on your computer and then its libraries subfolder (create it if it does not exist).
• Copy the custom library folders you downloaded from GitHub into that libraries folder.

Get the sensor's credential

Every sensor is issued an upload credential when it is created, and only a digest of it is stored on the server — so it is shown to you once, on the sensor's page, in the banner that appears the moment you press Save Sensor. Three values, with the pair this sensor's mode uses listed first and marked this sensor: the Key id (signed requests) and Signing key for signed mode, and the Token (legacy bearer token) for legacy mode. Copy them somewhere safe before leaving that page.

1. If you still have the banner from Step 1, you already have the credential — skip to How this device authenticates below.
2. If you have left the page, the value is gone and the server cannot recover it. Open the sensor from the Sensors list, expand API access & tokens, press Rotate credential and confirm: that mints a new credential and shows the same three values once. The previous one stops working immediately, so rotate only when the device has not been programmed yet — or is about to be re-programmed.
3. Check How this device authenticates. New sensors default to Signed requests (recommended), where the device sends its key id and an HMAC signature and the secret never leaves it. If your firmware cannot sign (check which scheme the sketch you are using implements), choose Legacy bearer token and save the sensor. The API documentation's Upload section describes both modes exactly.

Configure and upload the code

• Open Mayfly_Code_CustomAPI.ino in the Arduino IDE.
• Set the site_name variable to the sensor's storage key from Step 1 (for a new sensor, exactly the site code you typed).
• Paste the credential from the step above into the api_key variable.
• Connect the Mayfly to your computer over USB.
• Select the board (Tools > Board > EnviroDIY Mayfly) and the correct port (Tools > Port).
• Press Upload (the right-arrow icon).

Verify data transmission

• After the upload succeeds, open the Serial Monitor (Tools > Serial Monitor).
• Set the baud rate in the bottom-right corner to 57600.
• Watch for success messages confirming that readings are being sent to the Geronimo IoT API.
• On the server, the sensor's badge on the Sensors list changes from No data yet to Active once the first reading lands, and its variables appear on the Settings page.

That is it: the device is sending data and any alert rules you write on the sensor will be evaluated against it.

Step 3: Show the sensor on a map and the analytics page (optional)

This is done from the Settings page — no code edits needed. Find the new sensor's card, tick Public (a new sensor is private until someone with Settings permission publishes it), then Show on analytics and/or Show on map. The map also needs a Latitude and Longitude on the card, or a station that supplies them. Use the Pages and Maps pickers beside those switches to put the sensor on a particular analytics page or map, give each variable a label and unit, and press Save. The map and analytics pages read this configuration automatically. See Settings for every setting on the card.