MCUBoot Over-the-Air Download (OAD)
###################################

The following sections aim to describe the lower layers of OAD software that are
common across all protocol stack implementations. This includes the OAD image
header, the flash layout, Secure Bootloader, and the oad image tool.

.. warning::

    The BLE-Stack OAD Profile does not implement or perform any security or
    authentication mechanisms as part of the firmware update process.
    System developers should take measures to adequately authenticate peer
    devices and only accept and/or apply firmware images transferred from
    trusted sources via the OAD Profile. TI recommends applications use
    Bluetooth LE Secure Connections (LESC) with Man-in-the-Middle (MITM)
    protection with peer devices when performing wireless firmware updates,
    although the use of the LESC feature does not itself guarantee image
    authenticity.

    When using the Secure OAD feature along with recommended parameters,
    firmware images are authenticated on the device using ECDSA signature
    validation algorithms to ensure image authenticity prior to updating the
    running firmware image. Just as with the OAD Profile, TI recommends
    applications use Bluetooth LE Secure Connections with Man-in-the-Middle (MITM)
    protection with peer devices when performing wireless firmware updates.

.. ifconfig:: device == 'cc23xx'

    .. toctree::
        /oad-mcuboot/intro
        /oad-mcuboot/oad-types
        /oad-mcuboot/mcuboot
        /oad-mcuboot/on-chip-stack-library
        /oad-mcuboot/image-header
        /oad-mcuboot/flash-layout-on-chip-stack-library
        /oad-mcuboot/flash-layout-off-chip
        /oad-mcuboot/flash-layout-dual-image-cc23xx
        /oad-mcuboot/imgtool

.. ifconfig:: device != 'cc23xx'

    .. toctree::
        /oad-mcuboot/intro
        /oad-mcuboot/oad-types
        /oad-mcuboot/mcuboot
        /oad-mcuboot/on-chip-stack-library
        /oad-mcuboot/image-header
        /oad-mcuboot/flash-layout-on-chip-stack-library
        /oad-mcuboot/flash-layout-off-chip
        /oad-mcuboot/imgtool

The following sections aim to describe the |STACK| specific application and
profile layer of the OAD solution. The OAD application section will describe
the BLE OAD process from a high level in terms of events and states, and the
profile section will cover the actual structures that are sent over the air.

.. comment out the OAD doxygen for now
    See :ref:`oad_reference` for more information about the various OAD APIs and
    structures.

.. toctree::
    /ble-stack-oad/mcuboot-oad-application
    /ble-stack-oad/mcuboot-oad-profile

.. Add back once SLA links are available for CC23xx (update of SLA content
   required)

.. comment out from here::

    .. _SimpleLink Academy OAD Fundamentals Module: https://dev.ti.com/tirex/explore/node?node=ACnG5QNDmI2jX1enNwHqCQ__BSEc4rl__LATEST
    
    The `SimpleLink Academy OAD Fundamentals Module`_ covers the out of the box
    demo for OAD using the |STACK|. It can be found here.
    This lab contains the following step by step instructions:

    - Anatomy of an OAD
    
        - Image Header
        - Boot Image Manager (BIM)
        - OAD Memory Layout
        - OAD Protocol/BLE Profile
	
    - Setting up the OAD Environment
    
        - OAD Distributor Setup
        - OAD Target Setup
        - Creating a Factory Image
      
    - Running the OAD Demo
    
        - Modifying the Image Version
        - OAD using BTool
        - Btool Image Header Dialog
      
    - Reverting to a Factory Image
    
    .. _SimpleLink Academy OAD Advanced Module: https://dev.ti.com/tirex/explore/node?node=ACnG5QNDmI2jX1enNwHqCQ__BSEc4rl__LATEST
    
    The `SimpleLink Academy OAD Advanced Module`_ covers these advanced topics and
    instructions:

    - Adding OAD to an Existing Project
    
        - Project Changes
        - Code Changes
    
    - Advanced OAD Debugging
    - Creating a Production Image
    
        - Change to Release BIM
        - Secure OAD: Change default keys
        - Loading a Production Image
        - Combined Production Image
    
    Mobile developers wishing to make applications that integrate the TI OAD
    should refer to the following sample implementations. These are intended
    as reference libraries that implement the TI OAD Downloader for Android and iOS.
    
        - ios-cocoapod-eoad_.
        - android-eoad_
    
    .. _ios-cocoapod-eoad: https://git.ti.com/simplelink-ble-oad-ios
    .. _android-eoad: https://git.ti.com/simplelink-ble-oad-android

    .. note::
    
        The above libraries do not implement full fledged applications, but instead
        are intended to be integrated as part of an end application.
