Quickstart
Create a device and watch its first reading arrive: from a board on WiFi, a board with a SIM modem, or a single web request from any computer.
Choose your path
| You have | Path | Boards |
|---|---|---|
| A board and a WiFi network | Board on WiFi | ESP32, ESP8266, Raspberry Pi Pico W and Pico 2 W, Arduino UNO R4 WiFi, MKR WiFi 1010, Nano 33 IoT |
| A board, a 2G or 4G modem and a SIM card with data | Board with a SIM modem | ESP32, STM32, Raspberry Pi Pico and Pico 2, Arduino UNO R4, Zero and MKR, Mega, Uno, Nano |
| A computer, gateway, phone app or script, or no hardware yet | Web request | None needed |
A SIM modem is how equipment with no WiFi reaches MaxwellTrack: a borehole in a field, a tank on a hill, a vehicle. Every board except the ESP8266 can use one, and most 2G and 4G modems work: see Check your modem. The full list is in Supported boards.
What you need
- A MaxwellTrack account.
- Board on WiFi: the board and a USB cable. The network must be 2.4 GHz.
- Board with a SIM modem: the board, the modem, a SIM card with a data bundle, your mobile carrier's APN (often
internet), a USB cable, and a supply for the modem that can deliver 2 A peaks. - Web request: a terminal, or any tool that can send a web request.
1. Create a template
A template describes a kind of device: the readings it sends and the controls it accepts. Every device is created from one, so ten identical pumps share one template.
- 1
Open Templates
In the console sidebar, open Templates and choose New template. Name it after the equipment, for example
Cold room sensor. - 2
Add a datastream
On the template's Datastreams tab, add one named
Temperature, with keytemperature, data type Double and unit°C. The name is what people see everywhere; the key is what your code writes to.
2. Add a device
Open Devices, choose New device, give it a name, pick the template and create it. The device page opens.
3. Copy its credentials
On the device page, open the Settings tab and copy the Device ID. Under Access token, choose Regenerate and confirm with the code sent to your email. The token is shown once, so copy it now. More in Device ID and access token.
4. Send a reading
Pick the tab for your path. Each one sends the Temperature reading every 10 seconds; replace the example value with your sensor.
#include <maxwelltrack.h>
#define DEVICE_ID "YOUR_DEVICE_ID"
#define AUTH_TOKEN "YOUR_ACCESS_TOKEN"
#define WIFI_SSID "YOUR_WIFI_NAME"
#define WIFI_PASS "YOUR_WIFI_PASSWORD"
unsigned long lastSend = 0;
float readTemperature() {
return 4.2; // replace with your sensor reading
}
void setup() {
Serial.begin(115200);
MaxwellTrack.begin(DEVICE_ID, AUTH_TOKEN, WIFI_SSID, WIFI_PASS);
}
void loop() {
MaxwellTrack.run(); // keeps the device connected: call it on every pass
if (millis() - lastSend >= 10000) {
lastSend = millis();
MaxwellTrack.write("temperature", readTemperature()); // the datastream's key
}
}On a board with a SIM modem, wire modem TX to board RX, modem RX to board TX and a common ground. The ESP32 uses pins 16 and 17 (set in the sketch above); the UNO R4 Minima and Nano R4 use pins 0 and 1; the Uno, Nano and STM32 use other serial pins, which the library's cellular example sets up. To check that your modem works, see Check your modem.
5. Load the code on the board
| MCode IDE | Arduino IDE | |
|---|---|---|
| Install | Nothing: it runs in the browser and the library is included | The MaxwellTrack library, from Tools > Manage Libraries; for a SIM modem, TinyGSM as well |
| First load | Over USB, once | Over USB |
| Later changes | ESP32, ESP8266 and Raspberry Pi Pico: remotely, with Deploy. Other boards: a firmware file to flash over USB | Over USB |
| Guide | MCode IDE | Device library |
Pick your board, load the code, and open the serial monitor at 115200 baud to watch it connect.
6. Check it connected
- A board prints
[MaxwellTrack] Connecting... connectedon the serial monitor, and the device turns to Reporting in the console within a few seconds. On a SIM modem, the first connection can take a minute while the modem finds the network. - A web request answers
202 Acceptedwhen the reading is taken. The device report API page covers retries, timestamps and limits.
7. See it on the dashboard
Open the device's Dashboard tab, choose Edit dashboard, then Add widget. Pick Value or Chart, select the Temperature datastream and save. New readings appear the moment they arrive, without refreshing the page.
On a board
Keep run() in every pass of loop() and avoid long delay() calls. The library uses that time to stay connected and to receive commands.
If it does not connect
| What you see | Fix |
|---|---|
Serial monitor shows rc=5 | The Device ID or access token is wrong. Copy both again from the device's Settings tab. |
Serial monitor shows rc=-2 | No internet. On WiFi, check the network is 2.4 GHz and the password. On a SIM modem, check the APN, the signal, the data bundle and the modem's power supply. |
A web request answers 401 | The Device ID in the address or the token is wrong. |
| Reporting, but no value on the widget | The key in the code is not exactly the Temperature datastream's key. Keys are lower case: temperature, not Temperature. |
More causes and fixes are in Troubleshooting.
Next steps
- Control the equipmentSwitches and sliders on the dashboard that drive relays and setpoints.
- Act on the readingAlert someone when the cold room passes 8 °C, but not every ten seconds.
- Add more datastreamsReadings, controls, data types and units.
- Keep readings through outagesReadings written while offline are kept on the device and sent later.
- Cellular in depthWhich modems work, wiring for every board, signal strength and modem firmware.
- Run a whole siteProcess diagrams, alarms, protected controls and gateways.
Something unclear or out of date on this page? Tell support.
