Update startup script for dual frequency plans

[KevinWassermann94]

Packet Forwarder Region Changes and Restart Logic

@hotspot-maker,

To operate correctly on the Helium network, a Hotspot needs to use the appropriate frequency settings (also known as a band plan) for its asserted location. These settings are ultimately stored on the blockchain and can change from time to time. It is important that you have both:

• The most up-to-date band plans,
• Automated logic to detect plan changes and restart the packet forwarder when necessary

We ask that you please check the latest frequency plans and adopt automatic restart logic, as described further in this message.

Plan

The team plans to enact a changes to the blockchain which will require these new plans and logic on November 11, 2022.

Most-Recent Band Plans

Band plans in the Helium network are identified by their name, such as us915 or as923_1b. The most up-to-date band plans are available in the various JSON configuration files at

https://github.com/helium/sx1302_hal/tree/helium/hotspot/packet_forwarder (helium/hotspot branch)

Please make sure that your firmware is updated such that it has the frequency information in each of these plans available at hand, even if the radio hardware in any particular Hotspot may not be able to support it.

WARNING: Each of these files contains example calibration hardware calibration data – please take care to keep any independent radio calibration data you have for your Hotspots intact and only adopt the frequency data in these files.

Automated Restart Logic

Helium will soon be adopting a band plan change for several parts of the world, most notably Malaysia and Australia. This change will be enacted by an update to a Helium blockchain variable, which is ultimately queryable via the miner. In order to ensure that your Hotspots respond to the change appropriately it is important that they regularly query the miner at some interval (once per minute) and restart the packet forwarder upon any detected change.

If you have adopted the general region detection scheme outlined in https://docs.helium.com/mine-hnt/full-hotspots/become-a-maker/docker-integration#omit-region_override then you should already be familiar with the regulatory region query procedure that your firmware makes at system startup to determine the correct configuration file to supply to the packet forwarder at its startup:

Example startup script for SX1302-based radios:

#!/bin/bash
set -o pipefail

# Query asserted region name from miner
while !REGULATORY_REGION=$( $MINERDIR/miner info region | sed -e s/^region_// | tr a-z A-Z | tr -d '\r\n'); do
    sleep 10
done

# Start up packet forwarder with correct band plan
lora_pkt_fwd_sx1302 -c global_conf.json.sx1250.$REGULATORY_REGION

We ask that you now add a supervisory script that restarts the packet forwarder whenever there is a detected change in the region name for the Hotspot.

Example new supervisory restart script:

#!/bin/bash
set -o pipefail

get_region() {
    $MINER_DIR/miner info region | tr a-z A-Z | tr -d '\r\n'
}

# Wait until gateway service comes online.
while ! REGULATORY_REGION="$( get_region )"; do
    sleep 1
done

# Keep looping as long as region doesn't change.
while :; do
    while ! NEW_REGION=$( get_region ) || [ "$NEW_REGION" = "$REGULATORY_REGION" ]; do
        sleep 60
    done
    REGULATORY_REGION="$NEW_REGION"
    # At this point, the region has changed, and we need to
    # restart the packet forwarder.
    RESTART_PACKET_FORWARDER # Implement this for your firmware
done

[pritamghanghas]

@KevinWassermann94 this block is different in all our sx1302 global conf files: helium:

"precision_timestamp": {
      "enable": false,
      "max_ts_metrics": 255,
      "nb_symbols": 1
    },

our:

"fine_timestamp": {
        "enable": false,
        "mode": "all_sf" /* high_capacity or all_sf */
    },

the difference is reflected in our codebase as well. Leaving these as is as our codebase expects fine_timestamp

[pritamghanghas]

closing as it has been merged to production.