Class DeviceBootloader

Nested Relationships

Nested Types

Class Documentation

class DeviceBootloader

Represents the DepthAI bootloader with the methods to interact with it.

Public Types

using Type = dai::bootloader::Type
using Memory = dai::bootloader::Memory
using Section = dai::bootloader::Section
using UsbConfig = dai::bootloader::UsbConfig
using NetworkConfig = dai::bootloader::NetworkConfig
using Version = dai::Version

Public Functions

DeviceBootloader() = delete
explicit DeviceBootloader(const DeviceInfo &devInfo)

Connects to or boots device in bootloader mode depending on devInfo state; flashing not allowed

Parameters:

devInfo – DeviceInfo of which to boot or connect to

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBootloader(const DeviceInfo &devInfo, T allowFlashingBootloader)

Connects to or boots device in bootloader mode depending on devInfo state.

Parameters:

  • devInfo – DeviceInfo of which to boot or connect to

  • allowFlashingBootloader – (bool) Set to true to allow flashing the devices bootloader

DeviceBootloader(const DeviceInfo &devInfo, Type type, bool allowFlashingBootloader = false)

Connects to device in bootloader of specified type. Throws if it wasn’t possible. This constructor will automatically boot into specified bootloader type if not already running

Parameters:

  • devInfo – DeviceInfo of which to boot or connect to

  • type – Type of bootloader to boot/connect to.

  • allowFlashingBootloader – Set to true to allow flashing the devices bootloader. Defaults to false

DeviceBootloader(const DeviceInfo &devInfo, const fs::path &pathToBootloader, bool allowFlashingBootloader = false)

Connects to or boots device in bootloader mode depending on devInfo state with a custom bootloader firmware.

Parameters:

  • devInfo – DeviceInfo of which to boot or connect to

  • pathToBootloader – Custom bootloader firmware to boot

  • allowFlashingBootloader – Set to true to allow flashing the devices bootloader. Defaults to false

DeviceBootloader(std::string nameOrDeviceId, bool allowFlashingBootloader = false)

Connects to device with specified name/device id

Parameters:

  • nameOrDeviceId – Creates DeviceInfo with nameOrDeviceId to connect to

  • allowFlashingBootloader – Set to true to allow flashing the devices bootloader. Defaults to false

~DeviceBootloader()

Destroy the Device Bootloader object.

std::tuple<bool, std::string> flash(std::function<void(float)> progressCallback, const Pipeline &pipeline, bool compress = false, std::string applicationName = "", Memory memory = Memory::AUTO, bool checkChecksum = false)

Flashes a given pipeline to the device.

Parameters:

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • pipeline – Pipeline to flash to the board

  • compress – Compresses application to reduce needed memory size

  • applicationName – Name the application that is flashed

std::tuple<bool, std::string> flash(const Pipeline &pipeline, bool compress = false, std::string applicationName = "", Memory memory = Memory::AUTO, bool checkChecksum = false)

Flashes a given pipeline to the device.

Parameters:

  • pipeline – Pipeline to flash to the board

  • compress – Compresses application to reduce needed memory size

  • applicationName – Optional name the application that is flashed

ApplicationInfo readApplicationInfo(Memory memory)

Reads information about flashed application in specified memory from device

Parameters:

memory – Specifies which memory to query

std::tuple<bool, std::string> flashDepthaiApplicationPackage(std::function<void(float)> progressCallback, std::vector<uint8_t> package, Memory memory = Memory::AUTO)

Flashes a specific depthai application package that was generated using createDepthaiApplicationPackage or saveDepthaiApplicationPackage

Parameters:

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • package – Depthai application package to flash to the board

std::tuple<bool, std::string> flashDepthaiApplicationPackage(std::vector<uint8_t> package, Memory memory = Memory::AUTO)

Flashes a specific depthai application package that was generated using createDepthaiApplicationPackage or saveDepthaiApplicationPackage

Parameters:

package – Depthai application package to flash to the board

std::tuple<bool, std::string> flashClear(Memory memory = Memory::AUTO)

Clears flashed application on the device, by removing SBR boot structure Doesn’t remove fast boot header capability to still boot the application

std::tuple<bool, std::string> flashBootloader(std::function<void(float)> progressCallback, const fs::path &path = {})

Flashes bootloader to the current board

Parameters:

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • path – Optional parameter to custom bootloader to flash

std::tuple<bool, std::string> flashBootloader(Memory memory, Type type, std::function<void(float)> progressCallback, const fs::path &path = {})

Flash selected bootloader to the current board

Parameters:

  • memory – Memory to flash

  • type – Bootloader type to flash

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • path – Optional parameter to custom bootloader to flash

std::tuple<bool, std::string> flashUserBootloader(std::function<void(float)> progressCallback, const fs::path &path = {})

Flashes user bootloader to the current board. Available for NETWORK bootloader type

Parameters:

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • path – Optional parameter to custom bootloader to flash

std::tuple<bool, std::string> flashGpioModeBootHeader(Memory memory, int gpioMode)

Flash boot header which boots same as equivalent GPIO mode would

Parameters:

gpioMode – GPIO mode equivalent

std::tuple<bool, std::string> flashUsbRecoveryBootHeader(Memory memory)

Flash USB recovery boot header. Switches to USB ROM Bootloader

Parameters:

memory – Which memory to flash the header to

std::tuple<bool, std::string> flashBootHeader(Memory memory, int32_t frequency = -1, int64_t location = -1, int32_t dummyCycles = -1, int64_t offset = -1)

Flash optimized boot header

Parameters:

  • memory – Which memory to flasht the header to

  • frequency – SPI specific parameter, frequency in MHz

  • location – Target location the header should boot to. Default to location of bootloader

  • dummyCycles – SPI specific parameter

  • offset – Offset in memory to flash the header to. Defaults to offset of boot header

Returns:

status as std::tuple<bool, std::string>

std::tuple<bool, std::string> flashFastBootHeader(Memory memory, int32_t frequency = -1, int64_t location = -1, int32_t dummyCycles = -1, int64_t offset = -1)

Flash fast boot header. Application must already be present in flash, or location must be specified manually. Note - Can soft brick your device if firmware location changes.

Parameters:

  • memory – Which memory to flash the header to

  • frequency – SPI specific parameter, frequency in MHz

  • location – Target location the header should boot to. Default to location of bootloader

  • dummyCycles – SPI specific parameter

  • offset – Offset in memory to flash the header to. Defaults to offset of boot header

Returns:

status as std::tuple<bool, std::string>

std::tuple<bool, std::string> flashCustom(Memory memory, size_t offset, const std::vector<uint8_t> &data, std::function<void(float)> progressCb = nullptr)

Flash arbitrary data at custom offset in specified memory

Parameters:

  • memory – Memory to flash

  • offset – Offset at which to flash the given data in bytes

  • progressCallback – Callback that sends back a value between 0..1 which signifies current flashing progress

  • data – Data to flash

std::tuple<bool, std::string> flashCustom(Memory memory, size_t offset, const uint8_t *data, size_t size, std::function<void(float)> progressCb = nullptr)
std::tuple<bool, std::string> flashCustom(Memory memory, size_t offset, std::string filename, std::function<void(float)> progressCb = nullptr)
std::tuple<bool, std::string> readCustom(Memory memory, size_t offset, size_t size, std::vector<uint8_t> &data, std::function<void(float)> progressCb = nullptr)

Reads arbitrary data at custom offset in specified memory

Parameters:

  • memory – Memory to read

  • offset – Offset at which to read the specified bytes

  • size – Number of bytes to read

  • data – Data to read to. Must be at least ‘size’ number of bytes big

  • progressCallback – Callback that sends back a value between 0..1 which signifies current reading progress

std::tuple<bool, std::string> readCustom(Memory memory, size_t offset, size_t size, uint8_t *data, std::function<void(float)> progressCb = nullptr)
std::tuple<bool, std::string> readCustom(Memory memory, size_t offset, size_t size, std::string filename, std::function<void(float)> progressCb = nullptr)
std::tuple<bool, std::string, std::vector<uint8_t>> readCustom(Memory memory, size_t offset, size_t size, std::function<void(float)> progressCb = nullptr)
nlohmann::json readConfigData(Memory memory = Memory::AUTO, Type type = Type::AUTO)

Reads configuration data from bootloader

Parameters:

  • memory – Optional - from which memory to read configuration data

  • type – Optional - from which type of bootloader to read configuration data

Returns:

Unstructured configuration data

std::tuple<bool, std::string> flashConfigData(nlohmann::json configData, Memory memory = Memory::AUTO, Type type = Type::AUTO)

Flashes configuration data to bootloader

Parameters:

  • configData – Unstructured configuration data

  • memory – Optional - to which memory flash configuration

  • type – Optional - for which type of bootloader to flash configuration

std::tuple<bool, std::string> flashConfigFile(const fs::path &configPath, Memory memory = Memory::AUTO, Type type = Type::AUTO)

Flashes configuration data to bootloader

Parameters:

  • configPath – Unstructured configuration data

  • memory – Optional - to which memory flash configuration

  • type – Optional - for which type of bootloader to flash configuration

std::tuple<bool, std::string> flashConfigClear(Memory memory = Memory::AUTO, Type type = Type::AUTO)

Clears configuration data

Parameters:

  • memory – Optional - on which memory to clear configuration data

  • type – Optional - for which type of bootloader to clear configuration data

Config readConfig(Memory memory = Memory::AUTO, Type type = Type::AUTO)

Reads configuration from bootloader

Parameters:

  • memory – Optional - from which memory to read configuration

  • type – Optional - from which type of bootloader to read configuration

Returns:

Configuration structure

std::tuple<bool, std::string> flashConfig(const Config &config, Memory memory = Memory::AUTO, Type type = Type::AUTO)

Flashes configuration to bootloader

Parameters:

  • configData – Configuration structure

  • memory – Optional - to which memory flash configuration

  • type – Optional - for which type of bootloader to flash configuration

MemoryInfo getMemoryInfo(Memory memory)

Retrieves information about specified memory

Parameters:

memory – Specifies which memory to query

bool isUserBootloaderSupported()

Checks whether User Bootloader is supported with current bootloader

Returns:

true of User Bootloader is supported, false otherwise

bool isUserBootloader()

Retrieves whether current bootloader is User Bootloader (B out of A/B configuration)

void bootMemory(const std::vector<uint8_t> &fw)

Boots a custom FW in memory

Parameters:

fw –

Throws:

A – runtime exception if there are any communication issues

void bootUsbRomBootloader()

Boots into integrated ROM bootloader in USB mode

Throws:

A – runtime exception if there are any communication issues

Version getVersion() const
Returns:

Version of current running bootloader

bool isEmbeddedVersion() const
Returns:

True when bootloader was booted using latest bootloader integrated in the library. False when bootloader is already running on the device and just connected to.

Type getType() const
Returns:

Type of currently connected bootloader

bool isAllowedFlashingBootloader() const
Returns:

True if allowed to flash bootloader

void close()

Explicitly closes connection to device.

Note

This function does not need to be explicitly called as destructor closes the device automatically

bool isClosed() const

Is the device already closed (or disconnected)

Warning

This function is thread-unsafe and may return outdated incorrect values. It is only meant for use in simple single-threaded code. Well written code should handle exceptions when calling any DepthAI apis to handle hardware events and multithreaded use.

Public Static Functions

static std::tuple<bool, DeviceInfo> getFirstAvailableDevice()

Searches for connected devices in either UNBOOTED or BOOTLOADER states and returns first available.

Returns:

Tuple of boolean and DeviceInfo. If found boolean is true and DeviceInfo describes the device. Otherwise false

static std::vector<DeviceInfo> getAllAvailableDevices()

Searches for connected devices in either UNBOOTED or BOOTLOADER states.

Returns:

Vector of all found devices

static std::vector<uint8_t> createDepthaiApplicationPackage(const Pipeline &pipeline, const fs::path &pathToCmd = {}, bool compress = false, std::string applicationName = "", bool checkChecksum = false)

Creates application package which can be flashed to depthai device.

Parameters:

  • pipeline – Pipeline from which to create the application package

  • pathToCmd – Optional path to custom device firmware

  • compress – Optional boolean which specifies if contents should be compressed

  • applicationName – Optional name the application that is flashed

Returns:

Depthai application package

static std::vector<uint8_t> createDepthaiApplicationPackage(const Pipeline &pipeline, bool compress, std::string applicationName = "", bool checkChecksum = false)

Creates application package which can be flashed to depthai device.

Parameters:

  • pipeline – Pipeline from which to create the application package

  • compress – Specifies if contents should be compressed

  • applicationName – Name the application that is flashed

Returns:

Depthai application package

static void saveDepthaiApplicationPackage(const fs::path &path, const Pipeline &pipeline, const fs::path &pathToCmd = {}, bool compress = false, std::string applicationName = "", bool checkChecksum = false)

Saves application package to a file which can be flashed to depthai device.

Parameters:

  • path – Path where to save the application package

  • pipeline – Pipeline from which to create the application package

  • pathToCmd – Optional path to custom device firmware

  • compress – Optional boolean which specifies if contents should be compressed

  • applicationName – Optional name the application that is flashed

static void saveDepthaiApplicationPackage(const fs::path &path, const Pipeline &pipeline, bool compress, std::string applicationName = "", bool checkChecksum = false)

Saves application package to a file which can be flashed to depthai device.

Parameters:

  • path – Path where to save the application package

  • pipeline – Pipeline from which to create the application package

  • compress – Specifies if contents should be compressed

  • applicationName – Optional name the application that is flashed

static Version getEmbeddedBootloaderVersion()
Returns:

Embedded bootloader version

static std::vector<std::uint8_t> getEmbeddedBootloaderBinary(Type type = DEFAULT_TYPE)
Returns:

Embedded bootloader binary

Public Static Attributes

static constexpr const Type DEFAULT_TYPE = {Type::USB}

Default Bootloader type.

struct ApplicationInfo

Public Members

Memory memory
bool hasApplication
std::string firmwareVersion
std::string applicationName
struct Config : public bootloader::Config

Public Functions

void setStaticIPv4(std::string ip, std::string mask, std::string gateway)

Setting a static IPv4 won’t start DHCP client.

void setDynamicIPv4(std::string ip, std::string mask, std::string gateway)

Setting a dynamic IPv4 will set that IP as well as start DHCP client.

bool isStaticIPV4()

Get if static IPv4 configuration is set.

std::string getIPv4()

Get IPv4.

std::string getIPv4Mask()

Get IPv4 mask.

std::string getIPv4Gateway()

Get IPv4 gateway.

void setDnsIPv4(std::string dns, std::string dnsAlt = "")

Set IPv4 DNS options.

std::string getDnsIPv4()

Get primary IPv4 DNS server.

std::string getDnsAltIPv4()

Get alternate IPv4 DNS server.

void setUsbTimeout(std::chrono::milliseconds ms)

Set USB timeout.

std::chrono::milliseconds getUsbTimeout()

Get USB timeout.

void setNetworkTimeout(std::chrono::milliseconds ms)

Set NETWOR timeout.

std::chrono::milliseconds getNetworkTimeout()

Get NETWORK timeout.

void setMacAddress(std::string mac)

Set MAC address if not flashed on controller.

std::string getMacAddress()

Get MAC address if not flashed on controller.

void setUsbMaxSpeed(UsbSpeed speed)

Set maxUsbSpeed.

UsbSpeed getUsbMaxSpeed()

Get maxUsbSpeed.

nlohmann::json toJson() const

To JSON.

Public Static Functions

static Config fromJson(nlohmann::json)

from JSON

struct MemoryInfo

Public Members

bool available
std::int64_t size
std::string info