Added a guide to perform differential OTA udpate (#306)

config.toml

@@ -1086,6 +1086,7 @@ theme = "doc-theme"
     identifier = "updatefirmware@device"
     parent= "updatefirmware"
     weight = 10
+
 [[menu.main]]
     name = "Device (OTA)"
     url = "/updatefirmware/OTA/"
@@ -1093,6 +1094,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/"

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.
 

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/)

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.
+

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.