Skip to main content

Upgrade Gateway Firmware

Overview​

Upgrade the firmware of your KONA gateways from TEKTELIC KONA Core Network Server, without a visit to the site. You upgrade the BSP (the gateway's firmware package) of one gateway, or of every gateway in a gateway group at once. At the end, the gateways run the new BSP version, and KONA Core shows the result for each gateway.

KONA Core offers three ways to upgrade:

WayWhereUse it for
Upgrade BSP for a groupGateway group details > SW ManagementRecommended. All gateways of a group that have a new BSP version.
SW Management of one gatewayGateway details > SW ManagementOne gateway: test a new BSP first, or upgrade single software packages.
Apply upgradeGateways or Gateway groups list > UpgradeAn upgrade at a scheduled date and time.

We recommend that you upgrade one gateway first, check it, and then upgrade the rest of its group.

Before you start​

  • Role: Provider administrator or Customer administrator. User roles can't start upgrades, including from SW Management, or request software information from the gateway. They don't see the Upgrade menu. A Sub-Customer has no gateway pages. See Users, Roles & Permissions.
  • Gateways: TEKTELIC KONA gateways connected over MQTT and shown as Online. Remote commands, configurations and firmware upgrades are available only for these gateways. UDP gateways don't support these features. See Monitor Gateways.
  • Firmware source: you don't upload a firmware file. The gateway reports which upgradable packages and BSP versions are available to it, and KONA Core offers those. confirm where the gateway downloads the firmware from and the minimum BSP versions needed for an upgrade from KONA Core.
  • Maintenance window: the gateway reboots during a BSP upgrade, so it doesn't forward uplinks for a while. A BSP upgrade typically takes up to 1 hour, depending on the gateway and operating conditions. Plan the upgrade for a time with low traffic.

Steps​

  1. In the side menu, select Gateway groups.

  2. Select your gateway group in the list. The Gateway group details panel opens.

  3. Select the SW Management tab. The Gateways BSP versions table lists each gateway of the group with its GW-ID, BSP version, BSP new version and BSP upgrading status. KONA Core reads these values from the gateways, so the table can take a few seconds to fill.

    SW Management tab of a gateway group with the Gateways BSP versions table and the Upgrade BSP button. The BSP columns are empty because the screenshot tool blocks the commands that read them

  4. Check BSP upgrading status for each gateway. BSP upgrade is available means that BSP new version can be installed. BSP is up to date means that the gateway already runs the newest version.

  5. Select Upgrade BSP. KONA Core starts the upgrade right away, on every gateway that shows BSP upgrade is available. There is no confirmation dialog.

    warning

    Upgrade BSP reboots every gateway it upgrades, possibly several times. Don't turn off a gateway while its upgrade is in progress.

  6. Wait while BSP upgrading status shows Upgrade in progress. The message above the table shows the current state, for example Upgrade status: BSP Upgrade in progress. Do not turn off your board. The board may reboot several times.

  7. Wait for the message Upgrade status: BSP Upgrade Succeeded. If no gateway has an update, the message is Everything is upgraded.

Upgrade one gateway​

  1. In the side menu, select Gateways.

  2. Select the gateway in the list. The Gateway details panel opens.

  3. Select the SW Management tab. To find it, scroll the tab bar to the right.

    SW Management tab of a gateway with the SW versions type list and the Read Versions, BSP Status, Read Upgradable and Read Installable buttons. The Software versions table is empty because the screenshot tool blocks the commands that read it

  4. Select Read Versions. The Software versions table lists the installed Component packages and their Version. In SW versions type, Short List is the default. Select Full List to see all packages.

  5. Select BSP Status. A message shows the BSP state, for example BSP Latest or BSP Upgrade Busy.

  6. Select Read Upgradable. The Upgradable software table lists the packages that have a newer version, with Current Version and New Version. If the list is empty, it shows No packages available for upgrading.

  7. Select Upgrade BSP. This button appears only when a BSP upgrade is available. To upgrade other packages instead, select them and select Upgrade Selected, or select Upgrade All.

    If the list holds special packages, such as the BSP, KONA Core shows Special packages detected, bulk upgrade/install operations disabled. Then Upgrade All isn't available, and you upgrade the BSP with Upgrade BSP.

  8. Wait until the message above the table shows Upgrade status: BSP Upgrade Succeeded. While the upgrade runs, it shows BSP Upgrade in progress. Do not turn off your board. The board may reboot several times.

Read Installable lists packages that aren't installed yet. You install them with Install Selected or Install All. Install only packages that TEKTELIC Support recommends for your gateway.

Schedule an upgrade​

Apply upgrade sets a date and time at which the gateways download and install the update. You can apply it to selected gateways or to selected gateway groups.

  1. In the side menu, select Gateways. To upgrade whole groups, select Gateway groups instead.

  2. Select the checkbox of each gateway or group to upgrade. The toolbar shows how many are selected.

  3. Select Upgrade > Apply upgrade. The Apply upgrade dialog opens.

    Upgrade menu with Get upgrade status, Apply upgrade and Delete upgrade

  4. Optional: under Download, set the Date and Time at which the gateways download the update. In Max random delay, ms, enter a random delay in milliseconds, so that the gateways don't all download at the same moment.

  5. Under Update, set the Date and Time at which the gateways install the update. Both are required.

  6. In Max random delay, ms, enter the random delay for the installation in milliseconds. It's required. confirm a recommended delay for a large gateway group.

  7. Leave Force update cleared unless an upgrade fails because there isn't enough backup space. Force update allows the gateway to proceed with an upgrade when there isn't enough space for a backup.

    Apply upgrade dialog with Download and Update schedules, random delays and Force update

  8. Select Save.

The firmware API represents download and update times as milliseconds since the Unix epoch. confirm which firmware version a scheduled upgrade installs, and whether the date and time fields in the UI use UTC or the browser's time zone.

To cancel a scheduled upgrade, select the same gateways or groups, then Upgrade > Delete upgrade. Confirm in the dialog. This removes the scheduled upgrade, not the firmware that is installed.

Check the result​

  1. In the side menu, select Gateways.
  2. Select the checkbox of the upgraded gateways.
  3. Select Upgrade > Get upgrade status. The Firmware status table opens. For gateway groups, it also shows the GW group name.
  4. Check each gateway:
    • Current version shows the new firmware version.
    • Update Status shows the state the gateway reports, for example INSTALLED.
    • Available updates shows None when no newer version is left.
    • Last Successful Update Time shows when the last update finished.
  5. Select Close.

Firmware status table with the current version, update status and available updates of a gateway

Also check that each gateway shows Online and Active again after the upgrade. See Monitor Gateways. On the group's SW Management tab, the gateways show BSP is up to date.

Troubleshooting​

When an upgrade fails, the message above the table shows Upgrade status: followed by the gateway's error, for example Download error, Out of space, Bad signature, MD5 error or General upgrade failure. confirm whether a gateway keeps running its previous firmware after a failed BSP upgrade.

SymptomLikely causeWhat to do
The message shows Upgrade status: Download error.The gateway can't reach the firmware source.Check the gateway's internet connection, then start the upgrade again.
The message shows Upgrade status: Out of space.The gateway has too little free storage for the new package.Contact support before you retry. Don't remove packages by hand.
The message shows Command not supported, or the tables stay empty.The gateway is offline, connects over UDP, or its firmware doesn't support this command.Check that the gateway is Online and connects over MQTT. See Monitor Gateways.

Still stuck? A Customer contacts their Provider, and a Provider contacts TEKTELIC Support. Send the GW-ID, the gateway model, the current BSP version, the time of the upgrade in UTC, the exact message and a screenshot.