Line data    Source code

       1            0 : /*
       2              :  * Copyright (c) 2018-2023 O.S.Systems
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @brief UpdateHub Firmware Over-the-Air for Zephyr Project.
       9              :  * @defgroup updatehub UpdateHub Firmware Over-the-Air
      10              :  * @ingroup third_party
      11              :  * @{
      12              :  */
      13              : 
      14              : #ifndef ZEPHYR_INCLUDE_MGMT_UPDATEHUB_H_
      15              : #define ZEPHYR_INCLUDE_MGMT_UPDATEHUB_H_
      16              : 
      17              : #ifdef __cplusplus
      18              : extern "C" {
      19              : #endif
      20              : 
      21              : /**
      22              :  * @brief Responses messages from UpdateHub.
      23              :  *
      24              :  * @details These messages are used to inform the server and the
      25              :  * user about the process status of the UpdateHub and also
      26              :  * used to standardize the errors that may occur.
      27              :  *
      28              :  */
      29            0 : enum updatehub_response {
      30              :         UPDATEHUB_NETWORKING_ERROR = 0,
      31              :         UPDATEHUB_INCOMPATIBLE_HARDWARE,
      32              :         UPDATEHUB_UNCONFIRMED_IMAGE,
      33              :         UPDATEHUB_METADATA_ERROR,
      34              :         UPDATEHUB_DOWNLOAD_ERROR,
      35              :         UPDATEHUB_INSTALL_ERROR,
      36              :         UPDATEHUB_FLASH_INIT_ERROR,
      37              :         UPDATEHUB_OK,
      38              :         UPDATEHUB_HAS_UPDATE,
      39              :         UPDATEHUB_NO_UPDATE,
      40              : };
      41              : 
      42              : /**
      43              :  * @brief Runs UpdateHub probe and UpdateHub update automatically.
      44              :  *
      45              :  * @details The updatehub_autohandler handles the whole process
      46              :  * in pre-determined time intervals.
      47              :  */
      48            1 : __syscall void updatehub_autohandler(void);
      49              : 
      50              : /**
      51              :  * @brief The UpdateHub probe verify if there is some update to be performed.
      52              :  *
      53              :  * @return UPDATEHUB_HAS_UPDATE has an update available.
      54              :  * @return UPDATEHUB_NO_UPDATE no update available.
      55              :  * @return UPDATEHUB_NETWORKING_ERROR fail to connect to the UpdateHub server.
      56              :  * @return UPDATEHUB_INCOMPATIBLE_HARDWARE if Incompatible hardware.
      57              :  * @return UPDATEHUB_METADATA_ERROR fail to parse or to encode the metadata.
      58              :  */
      59            1 : __syscall enum updatehub_response updatehub_probe(void);
      60              : 
      61              : /**
      62              :  * @brief Apply the update package.
      63              :  *
      64              :  * @details Must be used after the UpdateHub probe, if you have updates to
      65              :  * be made, will perform the installation of the new image and the hardware
      66              :  * will rebooting.
      67              :  *
      68              :  * @return Return UPDATEHUB_OK if success
      69              :  * @return UPDATEHUB_NETWORKING_ERROR if fail to connect to the server.
      70              :  * @return UPDATEHUB_DOWNLOAD_ERROR fail while downloading the update package.
      71              :  * @return UPDATEHUB_INSTALL_ERROR fail while installing the update package.
      72              :  * @return UPDATEHUB_FLASH_INIT_ERROR fail to initialize the flash.
      73              :  */
      74            1 : __syscall enum updatehub_response updatehub_update(void);
      75              : 
      76              : /**
      77              :  * @brief Confirm that image is running as expected.
      78              :  *
      79              :  * @details Must be used before the UpdateHub probe. It should be one of first
      80              :  * actions after reboot.
      81              :  *
      82              :  * @return Return 0 if success otherwise a negative 'errno' value.
      83              :  */
      84            1 : __syscall int updatehub_confirm(void);
      85              : 
      86              : /**
      87              :  * @brief Request system to reboot.
      88              :  *
      89              :  * @return Return 0 if success otherwise a negative 'errno' value.
      90              :  */
      91            1 : __syscall int updatehub_reboot(void);
      92              : 
      93              : /**
      94              :  * @brief Report an update failure to the UpdateHub server.
      95              :  *
      96              :  * @details This sends an ERROR state (UPDATEHUB_STATE_ERROR) for the last package.
      97              :  *
      98              :  * @return 0 on success, negative errno on failure.
      99              :  */
     100            1 : __syscall int updatehub_report_error(void);
     101              : 
     102              : #ifdef __cplusplus
     103              : }
     104              : #endif
     105              : 
     106              : /**
     107              :  * @}
     108              :  */
     109              : 
     110              : #include <zephyr/syscalls/updatehub.h>
     111              : #endif /* ZEPHYR_INCLUDE_MGMT_UPDATEHUB_H_ */