diff --git a/config.toml b/config.toml index ad7ffe5..c5afaf5 100644 --- a/config.toml +++ b/config.toml @@ -1097,6 +1097,7 @@ theme = "doc-theme" identifier = "updatefirmware@device" parent= "updatefirmware" weight = 10 + [[menu.main]] name = "Device (OTA)" url = "/updatefirmware/OTA/" @@ -1104,6 +1105,13 @@ theme = "doc-theme" parent= "updatefirmware" weight = 20 +[[menu.main]] + name = "Device (Differential OTA)" + url = "/updatefirmware/diff_ota/" + identifier = "updatefirmware@diff_ota" + parent= "updatefirmware" + weight = 25 + [[menu.main]] name = "Expansion Board" url = "/updatefirmware/expansionboard/" diff --git a/content/firmwareapi/pycom/pycom.md b/content/firmwareapi/pycom/pycom.md index fbb363f..667052b 100644 --- a/content/firmwareapi/pycom/pycom.md +++ b/content/firmwareapi/pycom/pycom.md @@ -154,7 +154,7 @@ data = pulses_get(pin, 100) #### pycom.ota\_finish() -Perform a firmware update. These methods are internally used by a firmware update though FTP. The update starts with a call to `ota_start()`, followed by a series of calls to `ota_write(buffer)`, and is terminated with `ota_finish()`. After reset, the new image gets active. `buffer` shall hold the image data to be written, in arbitrary sizes. A block size of 4096 is recommended. +Perform a firmware update. These methods are internally used by a firmware update through FTP. The update starts with a call to `ota_start()`, followed by a series of calls to `ota_write(buffer)`, and is terminated with `ota_finish()`. After reset, the new image gets active. `buffer` shall hold the image data to be written, in arbitrary sizes. A block size of 4096 is recommended. Example: @@ -197,5 +197,11 @@ Instead of reading the data to be written from a file, it can obviously also be _Note: When the firmware is built with option_ `FS_USE_LITTLEFS` _the file system for_ `/flash` _is forced to be LittleFS._ * `safeboot` Enable or Disable safemoot mode. -* `reset` Set `True` to reset target after updating the `bootmgr` options , `False` for not resetting. +* `reset` Set `True` to reset target after updating the `bootmgr` options, `False` for not resetting. + +#### pycom.diff_update_enabled() + +Provides the status of the differential update feature. Returns `True` if differential update is enabled and `False` otherwise. `DIFF_UPDATE_ENABLED` build flag can be used to enable the differential update feature. + +> Note: This function is only available in the firmware versions which support differential update feature. If you get an exception while calling this function, your firmware version does not support this feature. diff --git a/content/tutorials/networks/lte/_index.md b/content/tutorials/networks/lte/_index.md index d292f90..ac0b31a 100644 --- a/content/tutorials/networks/lte/_index.md +++ b/content/tutorials/networks/lte/_index.md @@ -4,12 +4,10 @@ aliases: - chapter/tutorials/lte --- -The following tutorials demonstrate the use of the LTE CAT-M1 and NB-IoT functionality on cellular enabled Pycom modules. +The following tutorial demonstrates the use of the LTE CAT-M1 and NB-IoT functionality on cellular enabled Pycom modules. -Our cellular modules support both LTE CAT-M1 and NB-IoT, these are new lower power, long range, cellular protocols. These are not the same as the full version of 2G/3G/LTE supported by cell phones, and require your local carriers to support them. At the time of writing, CAT-M1 and NB-IoT connectivity is not widely available so be sure to check with local carriers if support is available where you are. +GPy and FiPy support both LTE CAT-M1 and NB-IoT. These are newer, low power, long range, cellular protocols. They are not the same as the full version of 2G/3G/LTE supported by cell phones, and require your local carriers to support them. At the time of writing, CAT-M1 and NB-IoT connectivity is not widely available so be sure to check with local carriers if support is available where you are. Together with the SIM card, the provider will supply you with configuration details: Usually band and APN. Use these in the example code below. -Both networks make can make use of the same example: -(Make sure you check the coverage map of your provider to confirm coverage in your area) ```python from network import LTE import time @@ -18,7 +16,10 @@ import socket lte = LTE() lte.init() #some carriers have special requirements, check print(lte.send_at_cmd("AT+SQNCTM=?")) to see if your carrier is listed. -# e.g. lte.init(carrier='verizion') +#when using verizon, use +#lte.init(carrier=verizon) +#when usint AT&T use, +#lte.init(carrier=at&t) #some carriers do not require an APN #also, check the band settings with your carrier @@ -26,9 +27,11 @@ lte.attach(band=20, apn="your apn") print("attaching..",end='') while not lte.isattached() time.delay(0.25) + print('.',end='') print(lte.send_at_cmd('AT!="fsm"')) # get the System FSM print("attached!") + lte.connect() print("connecting [##",end='') while not lte.isconnected(): @@ -39,13 +42,10 @@ while not lte.isconnected(): print("] connected!") print(socket.getaddrinfo('pycom.io', 80)) - -lte.disconnect() -lte.detach() lte.deinit() #now we can safely machine.deepsleep() ``` -The last line of the script should return a tuple containing the IP address of the Pycom server. +The last line of the script should return a tuple containing the IP address of the Pycom webserver. >Note: the first time, it can take a long while to attach to the network. @@ -69,8 +69,11 @@ lte.lte_callback(LTE.EVENT_COVERAGE_LOSS, cb_handler) ``` # LTE Troubleshooting guide -Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If you are having trouble attaching to the network, or getting a connection up and running, this might give some direction into what is wrong. We are mainly looking at the status of the top two indicators for now. -* Before calling `lte.attach()`, the status will be `STOPPED`. + + +Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If you are having trouble attaching to the network, or getting a connection up and running, this might give some direction into what you are looking for. We are mainly looking at the status of the top two indicators for now. +1. Before calling `lte.attach()`, the status will be `STOPPED`. + ``` SYSTEM FSM ========== @@ -96,7 +99,7 @@ Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If yo | HP CAT FSM |IDLE | +--------------------------+--------------------+ ``` -* With no SIM card detected, the `RRC TOP FSM` will keep status `CAMPED`. You will see `HP USIM FSM` marked `ABSENT`. +1. With no SIM card detected, the `RRC TOP FSM` will keep status `CAMPED`. You will see `HP USIM FSM` marked `ABSENT`. ``` SYSTEM FSM ========== @@ -122,19 +125,13 @@ Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If yo | HP CAT FSM |NULL | +--------------------------+--------------------+ ``` -* SIM card inserted and attaching: +1. SIM card inserted and attaching: * While `SCANNING`, the `RRC SEARCH FSM` goes from `WAIT_RSSI` to `WAIT_CELL_ID` * Later, the `RRC TOP FSM` goes from `SCANNING` to `SYNCING` * There are some states in between not discussed here. * If it is stuck at `WAIT_RSSI`, check the antenna connection * If the system returns multiple times from `SYNCING` to `CAMPED`, check the network availability, simcard placement and / or the firmware version. - >Note: Use the following to check the version number: - >```python - >import sqnsupgrade - >print(sqnsupgrade.info() - >``` - >* Versions LR5.xx are for CAT-M1 - >* Versions LR6.xx are for NB-IoT + ``` SYSTEM FSM @@ -161,7 +158,7 @@ Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If yo | HP CAT FSM |IDLE | +--------------------------+--------------------+ ``` -* Connecting +1. Connecting ``` SYSTEM FSM ========== @@ -187,7 +184,7 @@ Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If yo | HP CAT FSM |IDLE | +--------------------------+--------------------+ ``` -* Connected, note that `EMM MAIN FSM` has state `REGISTERED`. After a while, the `RRC TOP FSM` will have state `CAMPED`. +1. Connected ``` SYSTEM FSM ========== @@ -213,7 +210,15 @@ Below, we review the responses from `print(lte.send_at_cmd('AT!="fsm"'))`. If yo | HP CAT FSM |IDLE | +--------------------------+--------------------+ ``` -* During and after `lte.connect()` we cannot call the `print(lte.send_at_cmd('AT!="fsm"'))` as the modem is in `data state`. + +* Firmware version: + Use the following to check the version number: + ```python + import sqnsupgrade + sqnsupgrade.info() + ``` + * Versions LR5.xx are for CAT-M1 + * Versions LR6.xx are for NB-IoT * Potential other errors: * `OSError: [Errno 202] EAI_FAIL`: Check the data plan / SIM activation status on network - * `OSError: [Errno 113] ECONNABORTED`: \ No newline at end of file + diff --git a/content/updatefirmware/_index.md b/content/updatefirmware/_index.md index 983546c..c08e394 100644 --- a/content/updatefirmware/_index.md +++ b/content/updatefirmware/_index.md @@ -11,5 +11,6 @@ You can update the firmware of several different boards using different methods: * [Device](/updatefirmware/device/) * [Device (OTA)](/updatefirmware/ota/) +* [Device (Differential OTA)](/updatefirmware/diff_ota/) * [Expansion Board](/updatefirmware/expansionboard/) * [LTE Modem](/updatefirmware/ltemodem/) diff --git a/content/updatefirmware/diff_ota.md b/content/updatefirmware/diff_ota.md new file mode 100644 index 0000000..fb7dbc5 --- /dev/null +++ b/content/updatefirmware/diff_ota.md @@ -0,0 +1,61 @@ +--- +title: "Differential OTA Update" +aliases: + - updatefirmwate/diff_ota.html + - updatefirmwate/diff_ota.md + - chapter/updatefirmwate/diff_ota + +--- + +Differential update allows you to update your device using a differential update file (patch file) instead of a complete new binary. This can save a considerable amount of space and bandwidth while downloading the new firmware. The exact size of the patch file depends on the differences between the source and the target versions and it will usually be quite small when upgrading to a successive version. + +> Note: You can only perform the differential updates if your current firmware version supports this feature. The target can be any version above `1.20`. You can check whether this feature is enabled in your firmware or not by calling `pycom.diff_update_enabled()` function. + +## Generating a Differential Update File + +The differential update files can be generated by using our `DiffCreator` tool which uses `bsdiff`. +In order to generate the differential update file, you will need the following tools and files: + +* [DiffCreator](/gitbook/assets/DiffCreator.tar.gz) +* Old firmware version binary +* New firmware version binary + +> Note: The binary files used for this are the *.bin* files generated after the firmware is built. If you have downloaded the firmware as a compressed archive, you can decompress it to find the *.bin* file. + +1. Download the `DiffCreator` tool using the above link. +2. After extracting the contents of the `DiffCreator` archive, navigate to the directory with the terminal and type `make` to build the utility. +3. After building you can run the following command in the terminal to generate the patch file: + +``` +./diff_creator source.bin target.bin patch.bin +``` + +* `source.bin` is the current binary of your device, +* `target.bin` is the target binary +* `patch.bin` is the name of the patch file that you want to be generated. + + +> Note: replace the `.bin` filenames with the actual filenames. + +This will create the *patch.bin* file which can be used to upgrade your firmware instead of *target.bin* file. + + +## Using the Differential Update File + +To apply the differential update, use any of the methds described [here](../ota) by using your generated differential update file (e.g. patch.bin) as the new firmware binary. + +The following message will be displayed on REPL when a differential update file is detected by the device: + +``` +Differential Update Image detected. Restart the device to apply the patch. +``` + +After this, the device must be restarted so that the patch can be applied. After restart, you should see the following messages in REPL: + +``` +Patching the binary... +Patching SUCCESSFUL. +``` + +After patching is done, the device will restart again automatically and this time the updated firmware will be loaded. + diff --git a/content/updatefirmware/ota.md b/content/updatefirmware/ota.md index 4aa098b..dc1d882 100644 --- a/content/updatefirmware/ota.md +++ b/content/updatefirmware/ota.md @@ -12,8 +12,7 @@ Pycom modules come with the ability to update the devices firmware, while it is ## Pybytes 1. Go to your device (make sure it is connected to the platform!) 2. Click on the configuration tab -3. Use the OTA firmware update tool here -hello +3. Use the OTA firmware update tool there ## Method A @@ -21,7 +20,7 @@ Here we will describe one possible update methodology you could use that is impl Imagine you a smart metering company and you wish to roll out an update for your Pycom based smart meter. These meters usually send data back via LoRa. Unfortunately LoRa downlink messages have a very limited size and several hundred if not thousand would be required to upload a complete firmware image. To get around this you can have your devices sending their regular data via LoRa and when they receive a special command via a downlink message, the devices will connect to a WiFi network. It is unfeasible to ask customers to allow your device to connect to their home network so instead this network could be provided by a vehicle. This vehicle will travel around a certain geographic area in which the devices have been sent the special downlink message to initiate the update. The devices will look for the WiFi network being broadcast by the vehicle and connect. The devices will then connect to a server running on this WiFi network. This server (also shown in this example) will generate manifest files that instruct the device on what it should update, and where to get the update data from. -## Server +### Server Code available [here](https://github.com/pycom/pycom-libraries/blob/master/examples/OTA/OTA_server.py) @@ -128,7 +127,7 @@ In order for the URL's to be properly formatted you are required to send a "host GET /manifest.json?current_ver=1.0.0 HTTP/1.0\r\nHost: 192.168.1.144:8000\r\n\r\n ``` -## Client Library +### Client Library A MicroPyton library for interfacing with the server described above is available [here](https://github.com/pycom/pycom-libraries/blob/master/examples/OTA/1.0.0/flash/lib/OTA.py). @@ -137,7 +136,7 @@ This library is split into two layers. The top level `OTA` class implements all >Although the above code is functional, it is provided only as an example of how an end user might implement a OTA update mechanism. It is not 100% feature complete e.g. even though it does backup previous versions of files, the roll back procedure is not implemented. This is left of the end user to do. -## Example +### Example Below is am example implementing the methodology previously explained in this tutorial to initiate an OTA update. diff --git a/static/gitbook/assets/DiffCreator.tar.gz b/static/gitbook/assets/DiffCreator.tar.gz new file mode 100644 index 0000000..9665ca5 Binary files /dev/null and b/static/gitbook/assets/DiffCreator.tar.gz differ