From d5c9824aba6591c7d9a74425c558d4a4b85e7f10 Mon Sep 17 00:00:00 2001 From: Erol444 Date: Wed, 23 Aug 2023 20:29:56 -0400 Subject: [PATCH 1/2] Updated bootloader docs/examples --- docs/source/components/bootloader.rst | 14 ++++- .../samples/bootloader/bootloader_version.rst | 6 +- .../samples/bootloader/flash_bootloader.rst | 24 +++++--- .../bootloader/flash_user_bootloader.rst | 56 +++++++++++++++++++ docs/source/tutorials/code_samples.rst | 3 +- examples/bootloader/flash_bootloader.py | 21 ++++--- 6 files changed, 104 insertions(+), 20 deletions(-) create mode 100644 docs/source/samples/bootloader/flash_user_bootloader.rst diff --git a/docs/source/components/bootloader.rst b/docs/source/components/bootloader.rst index d9660e713..fc678f56b 100644 --- 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. + Boot switches ############# diff --git a/docs/source/samples/bootloader/bootloader_version.rst b/docs/source/samples/bootloader/bootloader_version.rst index 7b2479a78..77d00c926 100644 --- 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 index 4b4b9e32e..c52891777 100644 --- 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 ` to the connected OAK camera. It will +also clear the :ref:`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 new file mode 100644 index 000000000..1a2ac421e --- /dev/null +++ b/docs/source/samples/bootloader/flash_user_bootloader.rst @@ -0,0 +1,56 @@ +Flash User Bootloader +===================== + +This script will flash :ref:`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 `__ + + .. literalinclude:: ../../../../examples/bootloader/flash_user_bootloader.py + :language: python + :linenos: + + .. tab:: C++ + + Also `available on GitHub `__ + + .. 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 index 193a04370..4b96ba2a0 100644 --- 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 index b57234161..aca054781 100755 --- 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: From 9fc936aa20d831a0018bc4fe53da0bf6a7f838b4 Mon Sep 17 00:00:00 2001 From: Erol444 Date: Wed, 23 Aug 2023 20:33:20 -0400 Subject: [PATCH 2/2] Added info about bootloader priority in docs --- docs/source/components/bootloader.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/components/bootloader.rst b/docs/source/components/bootloader.rst index fc678f56b..68f4f199f 100644 --- a/docs/source/components/bootloader.rst +++ b/docs/source/components/bootloader.rst @@ -89,7 +89,7 @@ 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. +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 #############