.. module:: aws_iot_fota

************************************
Amazon Web Services IoT FOTA Library
************************************

The Zerynth AWS IoT FOTA Library can be used to implement Firmware Over The Air updates (FOTA) of AWS Things with ease.

Devices connected to the AWS IoT MQTT Broker can receive jobs containing enough information for a firmware update. Such jobs can be easily generated by the :ref:`ZTC <ztc-cmd-aws-iot_fota_start>`.

The FOTA flow is quite simple:

    * A device is notified of a new job
    * The job document must contain the following required fields:

        * :samp:`bc_idx`, the index of the bytecode slot to save the new firmware to
        * :samp:`bc_crc`, the MD5 crc of the new firmware
        * :samp:`bc_size`, the length in bytes of the new firmware
        * :samp:`bc_url`, a https url to a S3 file containing the new firmware

    * If the job can be performed, it is placed in the IN_PROGRESS status. Otherwise it is mared as FAILED and the flow stops.
    * The firmware is downloaded from :samp:`bc_url`, saved to the device and checked for errors against :samp:`bc_crc`
    * The device is restarted
    * If the new firmware is correct, the IN_PROGRESS job is retrieved and marked as SUCCEEDED. Otherwise the old working firmware will restart and will mark the job as FAILED.

The entire flow can be managed as in the following example: ::

    from aws.iot import fota as awsfota
    from aws.iot import jobs

    ...
    do some initialization (connect to the network and configure the Thing)
    ...
    
    # create an IoT Jobs object
    myjobs = jobs.Jobs(thing)
    
    # check if there are FOTA jobs waiting to be performed
    # This function executes a FOTA update if possible
    # or confirms an already executed FOTA update
    awsfota.handle_fota_jobs(myjobs, force=True)  # True, force

    while True:
        r = random(0,10)
        print('publish random sample...',r)
        thing.mqtt.publish("dev/sample", json.dumps({ 'asample': r }))
        sleep(publish_period)

        # check for new incoming jobs
        # again, FOTA is executed if a correct FOTA job is queued
        awsfota.handle_fota_jobs(myjobs)

    
.. function:: update(document)

    Given a correct job :samp:`document`, performs the FOTA update by downloading the correct firmware from the signed S3 bucket url
    and checking if the download was correct against the firmware CRC. Return True if the process finishes correctly.
    
    
.. function:: test(document)

    Must be called after a successful :ref:`update` to test the new firmware providing the job :samp:`document`. Once called, a device reset is necessary.
    
    
.. function:: confirm()

    Makes the new firmware final. Must be called by the new firmware upon reset after the old firmware called :ref:`test`. Failing to confirm the new firmware will reboot the old firmware on reset.
    
    
.. function:: reset()
   
   Reset the device

    
.. function:: handle_fota_jobs(jobs,force=False,disconnect_mqtt=True,auto_reset=True,job_cbk=None)

    The entire FOTA flow can be implemented by adding this function to an AWS ready firmware.
    
    The function arguments:

    * :samp:`jobs`, is an instance of the Jobs class (module aws.iot.jobs) properly initialized with the current Thing
    * :samp:`force`, if True forces the retrieval of pending and queued jobs regardless of a mqtt notification of the new jobs event
    * :samp:`disconnect_mqtt`, determines if th mqtt connection of the current Thing is closed before attempting a FOTA. By default it is set to True since keeping two TLS sockets open (one to the MQTT broker and the other to the S3 bucket) can be demanding for most devices.
    * :samp:`auto_reset`, automatically resets the device when the FOTA flow requires it. By default is set to True, however it can be disabled and the needed reset can be performed manually. A reset is signaled by :ref:`handle_fota_jobs` returning True.
    * :samp:`job_cbk`, is the job callback. Each non-FOTA job is passed to :samp:`job_cbk` for external handling if :samp:`job_cbk` is not None

    The function must be called at least twice: the first time, right after the connection to the mqtt broker with :samp:`force=True` in order to handle all pending jobs. The second call can be made periodically in the publish loop to catch new queued jobs.