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

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 requests as Notecard Outboard Firmware Update, 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 can be used to trigger a restart. Because they're environment variables, you can set them via the Notehub UI or the Notehub API. Environment variables can be set on one or more devices, fleets, and/or projects that are already deployed.

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

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

Reset Line Wiring

The reset line method utilizes two connections (the same connections required by Notecard Outboard Firmware Update).

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 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

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 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 API. Wiring ATTN only to a host GPIO won't restart the host.

Blues Notecarriers

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

For any other Notecarrier, or your own custom carrier board, wire the pins to your host as shown above. The Notecarrier datasheets show where each pin is broken out.

Configuring Notecard

Reset Line Configuration

To use the reset line, send Notecard a 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.

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

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

NoteRequest(req);

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 in its default off mode, or use dfu, neo-monitor, or track-neo-monitor modes.

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

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), or use the Notehub API's Set Device Environment Variables endpoint:

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) 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

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. You can also use Smart Fleets (see below) to programmatically identify fleets with host MCUs that may need to be restarted.

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.

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

A Smart Fleet 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:

$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

The 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 described above.

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

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

NoteRequest(req);

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

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 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), 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.

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

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

NoteRequest(req);

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

Troubleshooting Host Restarts

When Notecard can't restart a host over its reset line, it adds a Note to _health.qo whose text starts with can't restart host:, followed by one of these reasons:

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.

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.