# OTA Upgrade module
| Since  | Origin / Contributor  | Maintainer  | Source  |
| :----- | :-------------------- | :---------- | :------ |
| 2019-06-24 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [otaupgrade.c](../../components/modules/otaupgrade.c)|

The OTA Upgrade module provides access to the IDF Over-The-Air Upgrade
support, enabling new application firmware to be applied and booted into.

This module is not concerned with where the new application comes from.
The choice of download source and method (e.g. https, tftp) is left to
the user, as is the trigger to start an upgrade. A common approach is
to have the device periodically check in with a central server and
compare a provided version number with the currently running version,
and if necessary kick off an upgrade.

In order to use the `otaupgrade` module, there must exist at least two
OTA partitions (type `app`, subtype `ota_0` / `ota_1`), as well as the
"otadata" partition (type `data`, subtype `ota`). The IDF implements
the typical "flip-flop" approach to upgrades, in that one of the
partitions hosts the running application, and the upgrade is downloaded
into the inactive partition and only when fully downloaded and verified
is it marked as bootable. This makes the system resilient to incomplete
upgrades, be it due to power-loss, interrupted downloads, or other such
things.

An example partition table for OTA might look like:
```
# Name,  Type, SubType, Offset,  Size
nvs,      data, nvs,     0x9000,  0x5000
otadata,  data, ota,     0xe000,  0x2000
ota_0,    app,  ota_0,  0x10000,0x130000
ota_1,    app,  ota_1, 0x140000,0x130000
```

Depending on whether the installed boot loader has been built with or
without rollback support, the upgrade process itself has four or three
steps. Without rollback support, the steps are:

- `otaupgrade.commence()`
- feed the new application image into `otaupgrade.write(data)` in chunks
- `otaupgrade.complete(1)` to finalise and reboot into the new application

If the boot loader is built with rollback support, an extra step is needed
after the new application has booted (and been tested to be "good", by
whatever metric(s) the user chooses):

- `otaupgrade.accept()` to mark this image as valid, and allow it to be
  booted into again.

If a new firmware is not `accept()`ed before the device reboots, the
boot loader will switch back to the previous firmware version (provided
said boot loader is built with rollback support). A common test before
marking a new firmware as valid is to ensure the upgrade server can be
reached, on the basis that as long as the firmware can be remotely
upgraded, it's "good enough" to accept.

## otaupgrade.info()

The boot info and application state and version info can be queried with
this function. Typically it will be used to check the version of the
running application, to compare against a "desired" version in order
to decide whether an upgrade is required.

#### Syntax
`otaupgrade.info()`

#### Parameters
None.

#### Returns
A list of three values:

- the name of the partition of the running application
- the name of the partition currently marked for boot next (typically the
  same as the running application, but after `otaupgrade.complete()` it
  may point to a new application partition.
- a table whose keys are the names of OTA partitions and corresponding
  values are tables containing:
    - `state` one of `new`, `testing`, `valid`, `invalid`, `aborted` or
    possibly `undefined`. The values `invalid` and `aborted` largely
    mean the same things. See the IDF documentation for specifics.
    A partition in `testing` state needs to call `otaupgrade.accept()`
    if it wishes to become `valid`.
    - `name` the application name, typically "NodeMCU"
    - `date` the build date
    - `time` the build time
    - `version` the build version, as set by the *PROJECT_VER* variable
    during build
    - `secure_version` the secure version number, if secure boot is enabled
    - `idf_version` the IDF version

#### Example
```lua
boot_part, next_part, info = otaupgrade.info()
print("Booted: "..boot_part)
print("  Next: "..next_part)
for p,t in pairs(info) do
  print("@ "..p..":")
  for k,v in pairs(t) do
    print("    "..k..": "..v)
  end
end
print("Running version: "..info[boot_part].version)
```

## otaupgrade.commence()

Wipes the spare application partition and prepares to receive the new
application firmware.

If rollback support is enabled, note that the running application must
first be marked valid/accepted before it is possible to commence a
new OTA upgrade.

#### Syntax
`otaupgrade.commence()`

#### Parameters
None.

#### Returns
`nil`

A Lua error may be raised if the OTA upgrade cannot be commenced for some
reason (such as due to incorrect partition setup).


## otaupgrade.write(data)

Write a chunk of application firmware data to the correct partition and
location. Data must be streamed sequentially, the IDF does not support
out-of-order data as would be the case from e.g. bittorrent.

#### Syntax
`otaupgrade.write(data)`

#### Parameters
- `data` a string of binary data

#### Returns
`nil`

A Lua error may be raised if the data can not be written, e.g. due to the
data not being a valid OTA image (the IDF performs some checks in this
regard).


## otaupgrade.complete(reboot)

Finalises the upgrade, and optionally reboots into the new application
firmware right away.

#### Syntax
`otaupgrade.complete(reboot)`

#### Parameters
- `reboot` 1 to reboot into the new firmware immediately, nil to keep running

#### Returns
`nil`

A Lua error may be raised if the image does not pass validation, or no data
has been written to the image at all.

#### Example
```lua
-- Quick, dirty and totally insecure "push upgrade" for development use.
-- Use netcat to push a new firmware to a device:
--   nc -q 1 your-device-ip 9999 < build/NodeMCU.bin
--
osv = net.createServer()
osv:listen(9999, function(conn)
  print('Commencing OTA upgrade')
  local status, err = pcall(otaupgrade.commence)
  if err then
    print(err)
    conn:send(err)
    conn:close()
  end
  conn:on('receive', function(sck, data)
    status, err = pcall(function() otaupgrade.write(data) end)
    if err then
      print(err)
      conn:send(err)
      conn:close()
    end
  end)
  conn:on('disconnection', function()
    print('EOF, completing OTA')
    status, err = pcall(function() otaupgrade.complete(1) end)
    if err then
      print(err)
    end
  end)
end)

```

## otaupgrade.accept()

When the installed boot loader is built with rollback support, a new
application image is by default only booted once. During this "test run"
it can perform whatever checks is appropriate (like testing whether it
can still reach the update server), and if satisfied can mark itself
as valid. Without being marked valid, upon the next reboot the system
would "roll back" to the previous version instead.

#### Syntax
`otaupgrade.accept()`

#### Parameters
None.

#### Returns
`nil`


## otaupgrade.rollback()

A new firmware may decide that it is not performing as expected, and
request an explicit rollback to the previous version. If the call to this
function succeeds, the system will reboot without returning from the
call.

Note that it is also possible to roll back to a previous firmware
version even after the new version has called `otaupgrade.accept()`.

#### Syntax
`otaupgrade.rollback()`

#### Parameters
None.

#### Returns
Never. Either the system is rebooted, or a Lua error is raised (e.g. due
to there being no other firmware to roll back to).