Rate this page  

If you have a Notecard that is no longer communicating with Notehub or is repeatedly unable to connect to a cellular network, the Notecard may have been placed in a figurative "penalty box".

A penalty box is a state in which the Notecard is isolated and not allowed to even attempt a connection to a cellular network. Repeating a network connection failure multiple times can unnecessarily drain an attached battery. Therefore, the penalty box is set up to preserve battery life while also occasionally "opening up" and allowing the Notecard to attempt a new connection at certain intervals.

If you have enabled the capture of trace logs on a Notecard, you may see log events that refer to the penalty box, such as:

{"text":"penalty: entering penalty box: connect delayed (89 min remaining): can't open session to notehub: socket open PPP: ppp connection timeout? {service}{extended-service-failure}"}

{"text":"penalty: removed from penalty box: penalty period expired"}

In this guide we will look at the reasons why a Notecard may be placed in a penalty box and under which conditions a Notecard may be removed from a penalty box.

note

The failure of a Notecard to sync with Notehub does not necessarily mean it is in a penalty box. It could also be due the use of an invalid ProductUID or incorrect Notehub host name. These can be diagnosed in the response to a hub.sync.status command. For example:

{"req":"hub.sync.status"}

{"alert":true,"status":"connect delayed (60 min remaining): can't open session to discovery service: socket: cannot find host: blah.notefile.net {service}{host-unreachable} {service}{extended-service-failure}","time":1638397092,"completed":24}

There are four types of penalty boxes that a Notecard may enter after repeated failures:

  1. Insufficient Power Supply
  2. Network Registration Failure
  3. Inability to Connect to Notehub
  4. Inability to Acquire GPS Satellite Fix

Each penalty box is explained below including commands on how to manually remove a Notecard from a penalty box (when available).

If the Notecard reboots due to insufficient current supply while the modem is trying to register the Notecard on a cellular network, it will enter a penalty box. If the reboot is due to a card.restart, card.restore, or a DFU-induced restart, the Notecard will not enter a penalty box.

The length of time the Notecard is in the penalty box is 1/2 of the outbound sync interval or 120 minutes (whichever is greater). For each successive failure during modem registration, the penalty box interval grows by 120 minutes, up to a maximum of three days.

The Notecard will be released from the penalty box upon a successful registration on a cellular network, or if the host issues either:

  1. A hub.sync request with the allow:true parameter.
  2. A card.wireless.penalty request with the stop:true parameter.

If the cellular modem on the Notecard cannot register with a network within 120 seconds (or within 15 minutes if using NB-IoT), the Notecard will enter a network registration penalty box.

The length of time the Notecard is in the penalty box is extended by each successive network registration failure, by a minimum of 15 minutes. For each failure the previous delay is multiplied by 1.25 + 15 minutes, up to a maximum of 3 days. For example, the first set of retry intervals (in minutes) are: 15, 34, 58, 86, 123, 169, 227, and 298.

The Notecard will be released from the penalty box upon a successful registration on a cellular network, or if the host issues either:

  1. A hub.sync request with the allow:true parameter.
  2. A card.wireless.penalty request with the stop:true parameter.

If the cellular modem can successfully register with the network, but is unable to connect to Notehub, the Notecard may be placed in a "Notehub connection failure" penalty box.

The Notecard will enter this penalty box if connection failures to Notehub happen more than 3 consecutive times (if the Notecard is battery-powered) or 6 consecutive times (if the Notecard is USB/line-powered). The Notecard will remain in the penalty box for 1/2 of the configured outbound sync interval or 60 minutes, whichever is greater. Note that this penalty box will only come into play if there are no other network registration or power-related errors.

The Notecard will be released from the penalty box upon a successful registration on a cellular network, or if the host issues either:

  1. A hub.sync request with the allow:true parameter.
  2. A card.wireless.penalty request with the stop:true parameter.

If the Notecard is configured to acquire its location via GPS but is unable to make a position fix, it may be placed in a GNSS penalty box (provided all of the following conditions are met):

  1. The device is in motion (as determined by the on-board accelerometer).
  2. At least one GPS satellite is visible.
  3. A GPS position fix is NOT made within 15 minutes.

Please note that the if the GPS is not able to track any satellites at all, it is powered off after 90 seconds of searching and not placed in a penalty box (or it will be removed from the penalty box if it was already in one).

The length of time the Notecard is in the GNSS penalty box is 30 minutes multiplied by the number of consecutive GPS position fix failures (up to a maximum of 12 hours). This maximum duration of 12 hours would be reached after approximately 5 days of continuous GPS position fix failures.

The Notecard will be released from the GNSS penalty box if the GPS makes a position fix or if the GPS is unable to track any satellites for 90 seconds.