Merge pull request #886 from luxonis/update_bootloader

themarpe · web-flow · commit 5c659537fe15 · 2023-08-23T22:37:04.000-06:00
Updated bootloader docs/examples
diff --git a/docs/source/components/bootloader.rst b/docs/source/components/bootloader.rst
@@ -4,9 +4,9 @@ Bootloader
 ==========
 
 DepthAI bootloader is a small program which handles the booting process, either by **booting the flashed application** (see :ref:`Standalone mode`),
-or by **initializing the OAK PoE camera** so DepthAI API can connect to it. OAK PoE cameras already come with bootloader flashed at the factory.
+or by **initializing the OAK PoE camera** so DepthAI API can connect to it. OAK PoE cameras already come with factory bootloader flashed at the factory.
 
-Bootloader is part of the ``depthai`` library, so to eg. flash the newest bootloader, you should use the newest ``depthai`` library.
+Bootloader is bundled inside with the ``depthai`` library, so to eg. flash the newest bootloader, you should use the newest ``depthai`` library.
 
 Device Manager
 ##############
@@ -81,6 +81,16 @@ Device Manager will try to flash the user bootloader first, if flashed (factory)
 * **Factory reset** will erase the whole flash content and re-flash it with only the USB or NETWORK bootloader. Flashed application (pipeline, assets) and bootloader configurations will be lost.
 * **Boot into USB recovery mode** will force eg. OAK PoE camera to be available through the USB connector, even if its boot pins are set to PoE booting. It is mostly used by our firmware developers.
 
+Factory and User bootloader
+###########################
+
+There are two types of bootloaders:
+
+- **Factory bootloader**: bootloader that is flashed in the factory. We don't recommend re-flashing this bootloader, as it is not meant to be edited by end users.
+- **User bootloader**: bootloader that can be flashed by the user. If booting is unsuccessful (eg. gets corrupted when flashing), it will fallback to factory bootloader.
+
+USB devices don't support user bootloader. If device has User bootloader, it will be used by default. If user bootloader is not flashed, it will fallback to Factory bootloader.
+
 Boot switches
 #############
 
diff --git a/docs/source/samples/bootloader/bootloader_version.rst b/docs/source/samples/bootloader/bootloader_version.rst
@@ -16,8 +16,10 @@ Example script output
 .. code-block:: bash
 
     ~/depthai-python/examples$ python3 bootloader_version.py
-    Found device with name: 14442C10D1789ACD00-ma2480
-    Version: 0.0.15
+    Found device with name: 1.1
+    Version: 0.0.26
+    USB Bootloader - supports only Flash memory
+    Memory 'Memory.FLASH' size: 33554432, info: JEDEC ID: 01 02 19
 
 Setup
 #####
diff --git a/docs/source/samples/bootloader/flash_bootloader.rst b/docs/source/samples/bootloader/flash_bootloader.rst
@@ -1,10 +1,9 @@
 Flash Bootloader
 ================
 
-This script will flash bootloader to the connected OAK camera. Bootloader can only be flashed to devices that
-have flash on-board.
-
-Click on :ref:`Bootloader` for more information.
+This script will flash :ref:`factory bootloader <Factory and User bootloader>` to the connected OAK camera. It will
+also clear the :ref:`user bootloader <Factory and User bootloader>` (if it exists).
+:ref:`Bootloader` can only be flashed to devices that have on-board flash memory.
 
 .. note::
     We suggest using :ref:`Device Manager`, a GUI tool for interfacing with the bootloader and its configurations.
@@ -16,9 +15,20 @@ Example script output
 
 .. code-block:: bash
 
-    ~/depthai-python/examples$ python3 bootloader_version.py
-    Found device with name: 14442C1031425FD700-ma2480
-    Version: 0.0.15
+    ~/depthai-python/examples$ python3 flash_bootloader.py
+    [0] 1844301041C83D0E00 [X_LINK_USB_VSC]
+    Which DepthAI device to flash bootloader for [0..0]: 0
+    Booting latest bootloader first, will take a tad longer...
+    Bootloader version to flash: 0.0.26
+    No config found, skipping erasing user bootloader
+    Flashing USB bootloader...
+    Flashing progress: 0.0%
+    Flashing progress: 18.8%
+    Flashing progress: 31.2%
+    Flashing progress: 48.2%
+    Flashing progress: 94.2%
+    Flashing progress: 100.0%
+    Flashing successful. Took 7.55600329185836 seconds
 
 Setup
 #####
diff --git a/docs/source/samples/bootloader/flash_user_bootloader.rst b/docs/source/samples/bootloader/flash_user_bootloader.rst
@@ -0,0 +1,56 @@
+Flash User Bootloader
+=====================
+
+This script will flash :ref:`user bootloader <Factory and User bootloader>` to the connected OAK camera.
+:ref:`Bootloader` can only be flashed to devices that have on-board flash memory.
+
+.. note::
+    We suggest using :ref:`Device Manager`, a GUI tool for interfacing with the bootloader and its configurations.
+
+Demo
+####
+
+Example script output
+
+.. code-block:: bash
+
+    ~/depthai-python/examples/bootloader$ python3 flash_user_bootloader.py
+    [0] 1844301041C83D0E00 [X_LINK_USB_VSC] current bootloader: 0.0.26
+    Which DepthAI device to flash User Bootloader for (Note: Only NETWORK supported) [0..0]: 0
+    User Bootloader version to flash: 0.0.26
+    Flashing User Bootloader...
+    Flashing progress: 0.0%
+    Flashing progress: 18.8%
+    Flashing progress: 31.2%
+    Flashing progress: 48.2%
+    Flashing progress: 94.2%
+    Flashing progress: 100.0%
+    Flashing successful. Took 7.55600329185836 seconds
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/bootloader/flash_user_bootloader.py>`__
+
+        .. literalinclude:: ../../../../examples/bootloader/flash_user_bootloader.py
+           :language: python
+           :linenos:
+
+    .. tab:: C++
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-core/blob/main/examples/bootloader/flash_user_bootloader.cpp>`__
+
+        .. literalinclude:: ../../../../depthai-core/examples/bootloader/flash_user_bootloader.cpp
+           :language: cpp
+           :linenos:
+
+.. include::  /includes/footer-short.rst
diff --git a/docs/source/tutorials/code_samples.rst b/docs/source/tutorials/code_samples.rst
@@ -35,7 +35,8 @@ are presented with code.
 
 - :ref:`Bootloader Config` - Read/Flash/Clear bootloader on the device
 - :ref:`Bootloader Version` - Retrieves Version of Bootloader on the device
-- :ref:`Flash Bootloader` - Flash the bootloader to the device
+- :ref:`Flash Bootloader` - Flash factory bootloader to the device
+- :ref:`Flash User Bootloader` - Flash user bootloader to the device
 - :ref:`POE set IP` - Sets IP of the POE device
 
 .. rubric:: Calibration
diff --git a/examples/bootloader/flash_bootloader.py b/examples/bootloader/flash_bootloader.py
@@ -25,12 +25,12 @@
             with dai.DeviceBootloader(di) as bl:
                 print(f' current bootloader: {bl.getVersion()}', end='')
         print()
-    selected = input(f'Which DepthAI device to flash bootloader for [0..{len(deviceInfos)-1}]: ')
+    selected = input(f'Which OAK device to flash factory bootloader for [0..{len(deviceInfos)-1}]: ')
     info = deviceInfos[int(selected)]
 
 hasBootloader = (info.state == dai.XLinkDeviceState.X_LINK_BOOTLOADER)
 if hasBootloader:
-    print("Warning! Flashing bootloader can potentially soft brick your device and should be done with caution.")
+    print("Warning! Flashing factory bootloader can potentially soft brick your device and should be done with caution.")
     print("Do not unplug your device while the bootloader is flashing.")
     print("Type 'y' and press enter to proceed, otherwise exits: ")
     if input() != 'y':
@@ -54,15 +54,20 @@
             print("Prompt declined, exiting...")
             exit(-1)
 
+    try:
+        # Clears out user bootloader
+        configJson = bl.readConfigData()
+        configJson["userBlSize"] = 0
+        bl.flashConfigData(configJson)
+    except:
+        print('No config found, skipping erasing user bootloader')
+
     # Create a progress callback lambda
     progress = lambda p : print(f'Flashing progress: {p*100:.1f}%')
+
+    print(f"Flashing {blType.name} bootloader...")
     startTime = time.monotonic()
-    is_user_bl = bl.isUserBootloaderSupported()
-    print(f"Flashing {blType.name} {'USER' if is_user_bl else 'FACTORY'} bootloader...")
-    if is_user_bl:
-        (res, message) = bl.flashUserBootloader(progress)
-    else: # Factory bootloader
-        (res, message) = bl.flashBootloader(dai.DeviceBootloader.Memory.FLASH, blType, progress)
+    (res, message) = bl.flashBootloader(dai.DeviceBootloader.Memory.FLASH, blType, progress)
     if res:
         print("Flashing successful. Took", time.monotonic() - startTime, "seconds")
     else:
