Line data    Source code

       1            1 : /*
       2              :  * Copyright (c) 2020 Linumiz
       3              :  * Copyright (c) 2024 Vogl Electronic GmbH
       4              :  *
       5              :  * SPDX-License-Identifier: Apache-2.0
       6              :  */
       7              : 
       8              : /**
       9              :  * @file
      10              :  * @brief hawkBit main header file
      11              :  */
      12              : 
      13              : /**
      14              :  * @brief hawkBit Firmware Over-the-Air for Zephyr Project.
      15              :  * @defgroup hawkbit hawkBit Firmware Over-the-Air
      16              :  * @ingroup third_party
      17              :  * @{
      18              :  */
      19              : 
      20              : #ifndef ZEPHYR_INCLUDE_MGMT_HAWKBIT_HAWKBIT_H_
      21              : #define ZEPHYR_INCLUDE_MGMT_HAWKBIT_HAWKBIT_H_
      22              : 
      23              : #include <stdint.h>
      24              : 
      25              : /**
      26              :  * @brief Response message from hawkBit.
      27              :  *
      28              :  * @details These messages are used to inform the server and the
      29              :  * user about the process status of the hawkBit and also
      30              :  * used to standardize the errors that may occur.
      31              :  *
      32              :  */
      33            1 : enum hawkbit_response {
      34              :         /** matching events were not received within the specified time */
      35              :         HAWKBIT_NO_RESPONSE,
      36              :         /** an update was installed. Reboot is required to apply it */
      37              :         HAWKBIT_UPDATE_INSTALLED,
      38              :         /** no update was available */
      39              :         HAWKBIT_NO_UPDATE,
      40              :         /** fail to connect to the hawkBit server */
      41              :         HAWKBIT_NETWORKING_ERROR,
      42              :         /** image is unconfirmed */
      43              :         HAWKBIT_UNCONFIRMED_IMAGE,
      44              :         /** fail to get the permission to access the hawkBit server */
      45              :         HAWKBIT_PERMISSION_ERROR,
      46              :         /** fail to parse or to encode the metadata */
      47              :         HAWKBIT_METADATA_ERROR,
      48              :         /** fail while downloading the update package */
      49              :         HAWKBIT_DOWNLOAD_ERROR,
      50              :         /** fail to allocate memory */
      51              :         HAWKBIT_ALLOC_ERROR,
      52              :         /** hawkBit is not initialized */
      53              :         HAWKBIT_NOT_INITIALIZED,
      54              :         /** probe is currently running */
      55              :         HAWKBIT_PROBE_IN_PROGRESS,
      56              : };
      57              : 
      58              : /**
      59              :  * @brief Callback to provide the custom data to the hawkBit server.
      60              :  *
      61              :  * @details This callback is used to provide the custom data to the hawkBit server.
      62              :  * The custom data is used to provide the hawkBit server with the device specific
      63              :  * data.
      64              :  *
      65              :  * @param device_id The device ID.
      66              :  * @param buffer The buffer to store the json.
      67              :  * @param buffer_size The size of the buffer.
      68              :  */
      69            1 : typedef int (*hawkbit_config_device_data_cb_handler_t)(const char *device_id, uint8_t *buffer,
      70              :                                                   const size_t buffer_size);
      71              : 
      72              : /**
      73              :  * @brief Set the custom data callback.
      74              :  *
      75              :  * @details This function is used to set the custom data callback.
      76              :  * The callback is used to provide the custom data to the hawkBit server.
      77              :  *
      78              :  * @param cb The callback function.
      79              :  *
      80              :  * @retval 0 on success.
      81              :  * @retval -EINVAL if the callback is NULL.
      82              :  */
      83            1 : int hawkbit_set_custom_data_cb(hawkbit_config_device_data_cb_handler_t cb);
      84              : 
      85              : /**
      86              :  * @brief Init the flash partition
      87              :  *
      88              :  * @retval 0 on success.
      89              :  * @retval -errno if init fails.
      90              :  */
      91            1 : int hawkbit_init(void);
      92              : 
      93              : /**
      94              :  * @brief The hawkBit probe verify if there is some update to be performed.
      95              :  *
      96              :  * @return A value from ::hawkbit_response.
      97              :  */
      98            1 : enum hawkbit_response hawkbit_probe(void);
      99              : 
     100              : /**
     101              :  * @brief Request system to reboot.
     102              :  */
     103            1 : void hawkbit_reboot(void);
     104              : 
     105              : /**
     106              :  * @brief Callback to get the device identity.
     107              :  *
     108              :  * @param id Pointer to the buffer to store the device identity
     109              :  * @param id_max_len The maximum length of the buffer
     110              :  */
     111            1 : typedef bool (*hawkbit_get_device_identity_cb_handler_t)(char *id, int id_max_len);
     112              : 
     113              : /**
     114              :  * @brief Set the device identity callback.
     115              :  *
     116              :  * @details This function is used to set a custom device identity callback.
     117              :  *
     118              :  * @param cb The callback function.
     119              :  *
     120              :  * @retval 0 on success.
     121              :  * @retval -EINVAL if the callback is NULL.
     122              :  */
     123            1 : int hawkbit_set_device_identity_cb(hawkbit_get_device_identity_cb_handler_t cb);
     124              : 
     125              : /**
     126              :  * @brief Resets the hawkBit action id, that is saved in settings.
     127              :  *
     128              :  * @details This should be done after changing the hawkBit server.
     129              :  *
     130              :  * @retval 0 on success.
     131              :  * @retval -EAGAIN if probe is currently running.
     132              :  * @retval -EIO if the action id could not be reset.
     133              :  *
     134              :  */
     135            1 : int hawkbit_reset_action_id(void);
     136              : 
     137              : /**
     138              :  * @}
     139              :  */
     140              : 
     141              : #endif /* ZEPHYR_INCLUDE_MGMT_HAWKBIT_HAWKBIT_H_ */