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             :         /** fail to connect to the hawkBit server */
      37             :         HAWKBIT_NETWORKING_ERROR,
      38             :         /** image is unconfirmed */
      39             :         HAWKBIT_UNCONFIRMED_IMAGE,
      40             :         /** fail to get the permission to access the hawkBit server */
      41             :         HAWKBIT_PERMISSION_ERROR,
      42             :         /** fail to parse or to encode the metadata */
      43             :         HAWKBIT_METADATA_ERROR,
      44             :         /** fail while downloading the update package */
      45             :         HAWKBIT_DOWNLOAD_ERROR,
      46             :         /** image was already updated */
      47             :         HAWKBIT_OK,
      48             :         /** an update was installed. Reboot is required to apply it */
      49             :         HAWKBIT_UPDATE_INSTALLED,
      50             :         /** no update was available */
      51             :         HAWKBIT_NO_UPDATE,
      52             :         /** update was cancelled by the server */
      53             :         HAWKBIT_CANCEL_UPDATE,
      54             :         /** hawkBit is not initialized */
      55             :         HAWKBIT_NOT_INITIALIZED,
      56             :         /** probe is currently running */
      57             :         HAWKBIT_PROBE_IN_PROGRESS,
      58             : };
      59             : 
      60             : /**
      61             :  * @brief Callback to provide the custom data to the hawkBit server.
      62             :  *
      63             :  * @details This callback is used to provide the custom data to the hawkBit server.
      64             :  * The custom data is used to provide the hawkBit server with the device specific
      65             :  * data.
      66             :  *
      67             :  * @param device_id The device ID.
      68             :  * @param buffer The buffer to store the json.
      69             :  * @param buffer_size The size of the buffer.
      70             :  */
      71           1 : typedef int (*hawkbit_config_device_data_cb_handler_t)(const char *device_id, uint8_t *buffer,
      72             :                                                   const size_t buffer_size);
      73             : 
      74             : /**
      75             :  * @brief Set the custom data callback.
      76             :  *
      77             :  * @details This function is used to set the custom data callback.
      78             :  * The callback is used to provide the custom data to the hawkBit server.
      79             :  *
      80             :  * @param cb The callback function.
      81             :  *
      82             :  * @retval 0 on success.
      83             :  * @retval -EINVAL if the callback is NULL.
      84             :  */
      85           1 : int hawkbit_set_custom_data_cb(hawkbit_config_device_data_cb_handler_t cb);
      86             : 
      87             : /**
      88             :  * @brief Init the flash partition
      89             :  *
      90             :  * @retval 0 on success.
      91             :  * @retval -errno if init fails.
      92             :  */
      93           1 : int hawkbit_init(void);
      94             : 
      95             : /**
      96             :  * @brief The hawkBit probe verify if there is some update to be performed.
      97             :  *
      98             :  * @return A value from ::hawkbit_response.
      99             :  */
     100           1 : enum hawkbit_response hawkbit_probe(void);
     101             : 
     102             : /**
     103             :  * @brief Request system to reboot.
     104             :  */
     105           1 : void hawkbit_reboot(void);
     106             : 
     107             : /**
     108             :  * @brief Callback to get the device identity.
     109             :  *
     110             :  * @param id Pointer to the buffer to store the device identity
     111             :  * @param id_max_len The maximum length of the buffer
     112             :  */
     113           1 : typedef bool (*hawkbit_get_device_identity_cb_handler_t)(char *id, int id_max_len);
     114             : 
     115             : /**
     116             :  * @brief Set the device identity callback.
     117             :  *
     118             :  * @details This function is used to set a custom device identity callback.
     119             :  *
     120             :  * @param cb The callback function.
     121             :  *
     122             :  * @retval 0 on success.
     123             :  * @retval -EINVAL if the callback is NULL.
     124             :  */
     125           1 : int hawkbit_set_device_identity_cb(hawkbit_get_device_identity_cb_handler_t cb);
     126             : 
     127             : /**
     128             :  * @brief Resets the hawkBit action id, that is saved in settings.
     129             :  *
     130             :  * @details This should be done after changing the hawkBit server.
     131             :  *
     132             :  * @retval 0 on success.
     133             :  * @retval -EAGAIN if probe is currently running.
     134             :  * @retval -EIO if the action id could not be reset.
     135             :  *
     136             :  */
     137           1 : int hawkbit_reset_action_id(void);
     138             : 
     139             : /**
     140             :  * @}
     141             :  */
     142             : 
     143             : #endif /* ZEPHYR_INCLUDE_MGMT_HAWKBIT_HAWKBIT_H_ */