---
title: Restarting a Host MCU Remotely
description: Have Notecard restart a host MCU on command from Notehub or when the host stops responding, with the wiring, Notecard settings, and environment variables it needs.
source_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/restarting-a-host-mcu-remotely/
canonical_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/restarting-a-host-mcu-remotely/
markdown_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/restarting-a-host-mcu-remotely.md
---

# Restarting a Host MCU Remotely

Notecard has the ability to restart a connected host MCU by pulsing the host's reset line or by cutting its power. You can trigger a restart with environment variables, or let Notecard restart the host automatically when it stops sending requests, so a host that hangs in the field can recover without relying on its own firmware.

## How Host Restarts Work {#how-host-restarts-work}

When properly configured, Notecard can restart a host MCU over its **reset line (RST)** by pulling the host's reset pin `LOW` briefly, then releasing it. The reset line uses the same pins and the same [card.dfu](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-dfu) requests as [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md), so a host that's already set up for Outboard Firmware Update can also be restarted remotely.

> **Note:**
>
> If you set the `_restart_host_use_attn` environment variable, Notecard uses its `ATTN` pin instead of `RST`, and pulls it `LOW` for five seconds. With `ATTN` wired to the enable input of the host's power supply, that power-cycles the host.

The following [reserved environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#reserved-environment-variables) can be used to trigger a restart. Because they're environment variables, you can set them via the Notehub UI or the [Notehub API](https://dev.blues.io/api-reference/notehub-api.md). Environment variables can be set on one or more devices, fleets, and/or projects that are already deployed.

| Variable                          | Notecard restarts the host                           |
| --------------------------------- | ---------------------------------------------------- |
| `_restart_host`                   | Once, each time you set it to a new value            |
| `_restart_host_no_activity_hours` | When the host goes this many hours without a request |

Note that setting `_restart_host_use_attn` only chooses which of the two methods (i.e. `ATTN` pin or `RST` pin) Notecard uses.

### Requirements {#requirements}

- Notecard Cellular, Notecard Cell+WiFi, Notecard for Skylo, or Notecard WiFi. Notecard for LoRa doesn't support host restarts.
- Notecard firmware v5.1.1 or later.
- A connection from Notecard to the host's reset line or power enable, as described in [Wiring the Host](#wiring-the-host).

## Wiring the Host {#wiring-the-host}

### Reset Line Wiring {#reset-line-wiring}

The reset line method utilizes two connections (the same connections required by [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#required-wiring)).

| Notecard                    | Generic MCU                         | STM32   | ESP32 |
| --------------------------- | ----------------------------------- | ------- | ----- |
| `ALT_DFU_RESET` (or `AUX4`) | `NRST` (an active `LOW` reset line) | `NRST`  | `EN`  |
| `ALT_DFU_BOOT` (or `AUX3`)  | `B0`                                | `BOOT0` | `IO0` |

> **Note:**
>
> Notecard Cell+WiFi, Notecard for Skylo, and modern versions of Notecard Cellular have dedicated `ALT_DFU` pins. Other Notecards use `AUX3` and `AUX4`. Check the **Pin Information** section of your [Notecard's datasheet](https://dev.blues.io/datasheets/notecard-datasheet.md) if you're not sure.

To restart the host, Notecard drives the reset pin `LOW` for 100 ms (500 ms for ESP32 hosts) and then releases it. On STM32 and MCUboot hosts, Notecard leaves the `BOOT` pin floating during a restart, so the host needs its own pull resistor to hold `BOOT` at its normal boot level. Without one, the host can start in its ROM bootloader instead of your firmware. On ESP32 hosts, Notecard holds `IO0` `HIGH` through the restart.

### ATTN Pin Wiring {#attn-pin-wiring}

For the `ATTN` method, wire Notecard's `ATTN` pin to the active `HIGH` enable input of the regulator that powers your host. That's the same connection our guide on [host power management](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#host-power-management) uses. `ATTN` stays `HIGH` in normal operation, so the host remains powered until Notecard pulls `ATTN` `LOW` to restart it.

With this wiring, every use of `ATTN` controls the host's power, including the interrupt modes of the [card.attn](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-attn) API. Wiring `ATTN` *only* to a host GPIO won't restart the host.

### Blues Notecarriers {#blues-notecarriers}

These Notecarriers have the reset line wired to their host, and some can switch `ATTN` to the host's power enable.

| Notecarrier        | Reset line                                                                      | `ATTN`                                               |
| ------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Notecarrier CX     | Wired to the `ALT_DFU` pins                                                     | Not supported. Don't drive the `EN` pin from `ATTN`. |
| Notecarrier F v1.5 | Wired to the `ALT_DFU` pins                                                     | Set the `FEATHER_EN` switch to `N_ATTN`              |
| Notecarrier F v1.3 | Wired to `AUX3` and `AUX4` while the `AUX` switch is set to `DFU` (the default) | Set the `FEATHER_EN` switch to `N_ATTN`              |
| Notecarrier F v1.0 | Wired to `AUX3` and `AUX4` while the `DFU` switch is `ON`                       | Set the `Feather PWR` switch to `SWITCHED`           |

For any other Notecarrier, or your own custom carrier board, wire the pins to your host as shown above. The [Notecarrier datasheets](https://dev.blues.io/datasheets/notecarrier-datasheet.md) show where each pin is broken out.

## Configuring Notecard {#configuring-notecard}

### Reset Line Configuration {#reset-line-configuration}

To use the reset line, send Notecard a [card.dfu](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-dfu) request with the `name` of your host's MCU class (e.g. `stm32`, `stm32-bi`, `esp32`, or `mcuboot`). The example below is for a host wired to the `ALT_DFU` pins, as on Notecarrier CX and Notecarrier F v1.5. For a host wired to `AUX3` and `AUX4`, leave out `mode`.

**JSON**

```json
{
  "req": "card.dfu",
  "name": "stm32",
  "on": true,
  "mode": "altdfu"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);
JAddStringToObject(req, "mode", "altdfu");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.dfu"}
req["name"] = "stm32"
req["on"] = True
req["mode"] = "altdfu"
card.Transaction(req)
```

If your host is wired to `AUX3` and `AUX4`, those pins must stay free for the restart. Leave [card.aux](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux) in its default `off` mode, or use `dfu`, `neo-monitor`, or `track-neo-monitor` modes.

### ATTN Pin Configuration {#attn-pin-configuration}

To use the `ATTN` pin instead, set the `_restart_host_use_attn` environment variable (for example to `1`). This method doesn't need a `card.dfu` request.

> **Note:**
>
> Notecard only checks whether `_restart_host_use_attn` exists, not its value, so setting it to `0` or `false` still selects the `ATTN` pin. Delete the variable to switch back to the reset line.

## Restarting a Host from Notehub {#restarting-a-host-from-notehub}

To restart a host once, set the device's `_restart_host` environment variable to the current UNIX epoch time. In Notehub, open the device and add the variable on its **Environment** tab (see [Setting a Notehub Device Variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#setting-a-notehub-device-variable)), or use the Notehub API's [Set Device Environment Variables](https://dev.blues.io/api-reference/notehub-api/device-api.md#set-device-environment-variables) endpoint:

```bash
curl -X PUT
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/devices/<deviceUID>/environment_variables'
    -H 'Authorization: Bearer <access_token>'
    -H 'Content-Type: application/json'
    -d '{"environment_variables":{"_restart_host":"1792022400"}}'
```

Notecard will restart the host as soon as it receives the new value. A Notecard in `continuous` mode with `"sync":true` (see [`hub.set`](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-set)) should receive it in seconds; otherwise it arrives with the next inbound sync.

Notecard remembers the last `_restart_host` value it acted on, even across its own restarts, and only restarts the host when the value changes. Setting the same value again does nothing, so using the current time for each new restart is a useful tactic.

### Restarting Multiple Hosts {#restarting-multiple-hosts}

Note that if you set `_restart_host` at the fleet or project level, you will restart the host on every selected device (this includes any devices that join later, on their first sync). Be sure to delete the fleet or project variable once your devices have restarted, or avoid the problem by setting a device variable on each device instead, for example with a [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). You can also use [Smart Fleets](https://dev.blues.io/notehub/notehub-walkthrough.md#using-smart-fleet-rules) (see below) to programmatically identify fleets with host MCUs that may need to be restarted.

## Restarting a Host Automatically {#restarting-a-host-automatically}

Notecard can also restart a host on its own (i.e. without you setting `_restart_host` each time) to recover hosts that hang in the field. You can pair these automatic restarts with a hardware watchdog on the host itself, as described in [Design Host Firmware for Resilience](https://dev.blues.io/guides-and-tutorials/best-practices-for-production-ready-projects.md#design-host-firmware-for-resilience).

### When the Host Stops Responding {#when-the-host-stops-responding}

Set `_restart_host_no_activity_hours` to a number of hours, and Notecard restarts the host if it goes that long without sending a request. If the host stays silent, Notecard keeps restarting it at that interval. Notecard tracks this time in memory, so the count starts over whenever Notecard itself restarts, for example after a power loss or a `card.restart` request.

Be sure to choose a value longer than the longest time your host can go without a request, including any time it spends asleep. Otherwise Notecard will restart a host that's actually working normally.

### With Smart Fleets {#with-smart-fleets}

A [Smart Fleet](https://dev.blues.io/notehub/notehub-walkthrough.md#using-smart-fleet-rules) can pick out the devices whose hosts need a restart. Notehub runs the fleet's JSONata rule on each incoming event to add or remove the device, and a device picks up the fleet's environment variables the next time it syncs. Set `_restart_host` on the fleet to the current UNIX epoch time, and each device the rule adds restarts its host once.

For example, if your host firmware reports a count of failed sensor reads in its `sensor.qo` Notes, this rule (with the **Notefiles** filter set to `sensor.qo`) adds a device when the count passes 10, and removes it when a later Note reports 10 or fewer:

```jsonata
$exists(body.sensor_errors) ?
  (body.sensor_errors > 10) ? $addToFleet() : $removeFromFleet()
  : $leaveFleetAlone()
```

Because Notecard restarts the host only once per `_restart_host` value, a device that leaves the fleet and later rejoins won't restart again. Setting a new value restarts the host of every device in the fleet at that point.

### With an ATTN Watchdog {#with-an-attn-watchdog}

The [card.attn](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-attn) API's `watchdog` mode is a host-configured alternative to `_restart_host_no_activity_hours`. If Notecard doesn't receive a request within `seconds` (60 or more), it pulls `ATTN` `LOW` for five seconds, so it needs the [`ATTN` wiring](#attn-pin-wiring) described above.

**JSON**

```json
{
  "req": "card.attn",
  "mode": "watchdog",
  "seconds": 300
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "watchdog");
JAddNumberToObject(req, "seconds", 300);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "watchdog"
req["seconds"] = 300
card.Transaction(req)
```

Notecard forgets the watchdog when it restarts, so send this request each time the host starts.

## Other Events That Restart the Host {#other-events-that-restart-the-host}

If you've configured a `card.dfu` request with a `name` value, Notecard also restarts the host over its reset line every time Notecard itself starts, so that both start from a known state. That includes power-up, a [card.restart](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-restart) request, a Notecard firmware update, and the `_restart` environment variable. The same happens when Notecard wakes a host it put to sleep with the `card.attn` API's `sleep` mode (see [Host Power Management](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#host-power-management)), and at the end of every Outboard Firmware Update.

> **Note:**
>
> These restarts always use the reset line, even if `_restart_host_use_attn` is set.

To stop the restarts at startup and after sleep, send a `card.dfu` request with `"stop":true`, and send `"start":true` to turn them back on. This setting doesn't affect restarts triggered by the environment variables above.

**JSON**

```json
{
  "req": "card.dfu",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.dfu"}
req["stop"] = True
card.Transaction(req)
```

## Troubleshooting Host Restarts {#troubleshooting-host-restarts}

When Notecard can't restart a host over its reset line, it adds a Note to [\_health.qo](https://dev.blues.io/api-reference/system-notefiles.md#health-qo) whose text starts with `can't restart host:`, followed by one of these reasons:

| Reason                                                   | Fix                                                                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `dfu type not specified`                                 | Send `card.dfu` with a `name`, as shown in [Configuring Notecard](#configuring-notecard).                            |
| `dfu disabled`                                           | `card.dfu` was turned off. Send `card.dfu` with `"on":true`.                                                         |
| `dfu: reset error: incompatible aux mode (see card.aux)` | Another `card.aux` mode is using `AUX3` and `AUX4`. Set `card.aux` to `off`, or wire the host to the `ALT_DFU` pins. |
| `dfu: reset error: unrecognized firmware type`           | Set the `card.dfu` `name` to `stm32`, `stm32-bi`, `esp32`, or `mcuboot`.                                             |

Notecard counts a failed attempt as having handled that `_restart_host` value, so after fixing the problem, set `_restart_host` to a new value.

If the host didn't restart and there's no `_health.qo` Note, make sure `_restart_host` is a number that differs from the last value. For the `ATTN` method, also check that `ATTN` reaches the host's power enable, including the switch positions listed in [Blues Notecarriers](#blues-notecarriers).

If the host stops responding after a restart, check the pull resistor on its `BOOT` pin. The host may be starting in its ROM bootloader.