---
title: Using Environment Variables to Change Notecard Configuration
description: Learn how to use environment variables, both built-in and custom, to change Notecard configuration remotely.
source_url: https://dev.blues.io/blog/changing-notecard-config-with-env-vars/
canonical_url: https://dev.blues.io/blog/changing-notecard-config-with-env-vars/
markdown_url: https://dev.blues.io/blog/changing-notecard-config-with-env-vars.md
---

# Using Environment Variables to Change Notecard Configuration

![Using Environment Variables to Change Notecard Configuration banner](https://dev.blues.io/images/blog/posts/changing-notecard-config-with-env-vars/banner.jpg?v=18f8ca77)

February 13, 2025

## Learn how to use environment variables, both built-in and custom, to change Notecard configuration remotely.

- [Notecard](https://dev.blues.io/blog/tag/notecard)
- [Notehub](https://dev.blues.io/blog/tag/notehub)

[![TJ VanToll](https://dev.blues.io/images/blog/authors/tj-vantoll.jpg?v=c3d7f336)](https://dev.blues.io/blog/author/tj-vantoll/)

[TJ VanTollPrincipal Developer Advocate](https://dev.blues.io/blog/author/tj-vantoll/)

All Notecards require some level of configuration. This configuration may include how often a Notecard connects to Notehub ([`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#hub-set)), how a Notecard gets its GPS/GNSS location ([`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-location-mode)), and what radio access technologies a Notecard should use ([`card.transport`](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-transport)).

When you deploy a Notecard you must hardcode its default configuration, either by placing the initial config values in a [setup script](https://dev.blues.io/tools-and-sdks/notecard-cli.md?highlight=Notecard+CLI#run-a-setup-script) that runs as part of a provisioning process, or by using host firmware to give a Notecard its initial configuration.

In this article you’ll learn how to change your Notecard’s configuration, remotely, after your device has been deployed.

## Using Reserved Environment Variables

The easiest way to remotely change a Notecard’s configuration is with [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md), which are key-value pairs that can be set in the Notehub UI or through the Notehub API. Environment variables are easy to use, and propagate to devices in a project or fleet using the same synchronization mechanism used for Notes and Notefiles.

We provide a handful of [reserved environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#reserved-environment-variables) specifically for altering a Notecard’s configuration remotely. Here are a few of the most commonly used ones:

- `_gps_secs`: Used to override the `card.location.mode` request’s `seconds` argument, which controls how often a Notecard determines its GPS/GNSS location.

- `_gps_track`: Setting this variable to `1` is equivalent to using the `card.location.track` request’s `start` argument.

- `_sync_continuous`: Setting this variable to `1` is equivalent to setting a Notecard to `mode: "continuous"` through the `hub.set` request.

- `_sync_inbound_mins`: Used to override the `hub.set` request’s `inbound` argument, which determines how often a Notecard synchronizes to receive inbound data from Notehub.

- `_sync_outbound_mins`: Used to override the `hub.set` request’s `outbound` argument, which determines how often a Notecard synchronizes to send data to Notehub.

> **Note:**
>
> If you’re new to Blues and aren’t sure how to set these environment variables, check out the [Setting a Notehub Device Variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#setting-a-notehub-device-variable) documentation article.
>
> Also, note that after setting a variable, you must wait for your Notecard’s next inbound synchronization before your configuration change will take effect.

All of these environment variables act as overrides and take precedence over a Notecard’s default configuration. For example, if you use a Notecard’s `hub.set` request to set `{"inbound":60}`, and also have a `_sync_inbound_mins` environment variable on the device set to `120`, your Notecard will use `120` as an inbound interval.

If you [delete](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#deleting-environment-variables) any of these variables your device will revert back to its currently configured values. For instance, using the previous paragraph’s example, if you delete the `_sync_inbound_mins` variable your Notecard will revert to an inbound interval of `60` because of the `{"inbound":60}` configuration you used for the `hub.set` request.

## Creating Custom Environment Variables

Although we provide reserved environment variables for common configuration scenarios, we don’t provide built-in variables for each of the hundreds of ways you may wish to configure a Notecard.

If you want to change a Notecard’s default configuration and a reserved environment variable is not available, we recommend creating custom environment variables, and writing host firmware that uses those variables appropriately.

For example, suppose you are using a Notecard’s [`card.temp` request](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-temp) to receive regular temperature readings from your device.

```json
{
  "req": "card.temp",
  "minutes": 60
}
```

With the configuration above your device will take temperature readings every 60 minutes, but there is no way to change the `"minutes"` value remotely (aka no reserved environment variable exists for this purpose).

The code below shows a host firmware implementation that allows you to change your `"minutes"` value through a custom `card_temp_minutes` environment variable.

```c
int currentTempInterval;

void setupTempMonitoring(int minutes) {
  J *req = NoteNewRequest("card.temp");
  if (req != NULL) {
    JAddNumberToObject(req, "minutes", minutes);
    JAddBoolToObject(req, "sync", true);
    NoteRequest(req);
    currentTempInterval = minutes;
  }
}

void setup() {
  // all other setup your project may need to do

  setupTempMonitoring(10);
}

void loop() {
  J *req = NoteNewRequest("env.get");
  if (req != NULL) {
    JAddStringToObject(req, "name", "card_temp_minutes");
    if (J *rsp = NoteRequestResponse(req)) {
      char* minutesStr = JGetString(rsp, "text");
      int minutes = atoi(minutesStr);
      if (minutes > 0 && minutes != currentTempInterval) {
        setupTempMonitoring(minutes);
      }
      NoteDeleteResponse(rsp);
    }
  }

  delay(1000);
}
```

> **Note:**
>
> This is C code that uses [note-arduino](https://dev.blues.io/tools-and-sdks/firmware-libraries/arduino-library.md) (the official Arduino library for communicating with Notecards), but you can implement the same approach using any of the [Notecard’s firmware libraries](https://dev.blues.io/tools-and-sdks/firmware-libraries.md).

Let’s break down what’s happening here. First, we create a function that takes an integer `minutes` as an argument and invokes the `card.temp` request with its value. We also create a global `currentTempInterval` variable that stores the last-used value that we’ll reference later.

```c
int currentTempInterval;
void setupTempMonitoring(int minutes) {
  J *req = NoteNewRequest("card.temp");
  if (req != NULL) {
    JAddNumberToObject(req, "minutes", minutes);
    JAddBoolToObject(req, "sync", true);
    NoteRequest(req);
    currentTempInterval = minutes;
  }
}
```

In `setup()` we call our new `setupTempMonitoring()` function with a default value of `10`. This gives Notecard a default value to use for its `minutes` argument in case no environment variable is present.

```c
void setup() {
  // all other setup your project may need to do

  setupTempMonitoring(10);
}
```

And then finally, in `loop()`, we use Notecard’s [`env.get` request](https://dev.blues.io/api-reference/notecard-api/env-requests/latest.md#env-get) to get the latest value of the `card_temp_minutes` environment variable. If we find a valid value, and that value is different than the last-used value (`currentTempInterval`), we call our `setupTempMonitoring()` function again to update to the new `minutes` value.

```c
J *req = NoteNewRequest("env.get");
if (req != NULL) {
  JAddStringToObject(req, "name", "card_temp_minutes");
  if (J *rsp = NoteRequestResponse(req)) {
    char* minutesStr = JGetString(rsp, "text");
    int minutes = atoi(minutesStr);
    if (minutes > 0 && minutes != currentTempInterval) {
      setupTempMonitoring(minutes);
    }
    NoteDeleteResponse(rsp);
  }
}
```

> **Note:**
>
> If you’re writing more complex code with environment variables you may want to check out [Notecard Environment Variable Manager](https://github.com/blues/notecard-env-var-manager), an open-source C library we provide for fetching environment variables from a Notecard.

## Wrapping Up

Being able to configure your devices is important for any remote deployment. Notecard makes this process trivial, by providing reserved environment variables for common configuration options, and a rich environment variable feature for designing custom configuration mechanisms.

Try out this article’s approach, and if you have any questions let us know in the [comments](https://discuss.blues.com/t/using-environment-variables-to-change-notecard-configuration).