connector_api_firmware.h

00001 /*
00002  * Copyright (c) 2013 Digi International Inc.,
00003  * All rights not expressly granted are reserved.
00004  *
00005  * This Source Code Form is subject to the terms of the Mozilla Public
00006  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
00007  * You can obtain one at http://mozilla.org/MPL/2.0/.
00008  *
00009  * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
00010  * =======================================================================
00011  */
00012 
00013 #ifndef CONNECTOR_API_FIRMWARE_H
00014 #define CONNECTOR_API_FIRMWARE_H
00015 
00016 #if (defined CONNECTOR_FIRMWARE_SERVICE)
00017 
00018 /**
00019 * @defgroup connector_request_id_firmware_t Firmware Request IDs
00020 * @{
00021 */
00022 /**
00023 * Firmware Facility Request ID passed to the application's callback for firmware update interface.
00024 * The class id for this connector_request_id_firmware_t is connector_class_id_firmware.
00025 */
00026 typedef enum {
00027     connector_request_id_firmware_target_count,         /**< Requesting callback to return number of supported target for firmware update */
00028     connector_request_id_firmware_info,                 /**< Requesting callback to return the version number,
00029                                                              maximum code size, description and
00030                                                              regular expression for firmware update image name of specific target */
00031     connector_request_id_firmware_download_start,       /**< Requesting callback to start firmware update of specific target */
00032     connector_request_id_firmware_download_data,        /**< Callback is passed with image data for firmware update. This is called for each chunk of image data */
00033     connector_request_id_firmware_download_complete,    /**< Callback is called to complete firmware update. */
00034     connector_request_id_firmware_download_abort,       /**< Requesting callback to abort firmware update */
00035     connector_request_id_firmware_target_reset          /**< Requesting callback to reset the target */
00036 } connector_request_id_firmware_t;
00037 /**
00038 * @}
00039 */
00040 
00041 
00042 /**
00043 * @defgroup connector_firmware_count_t Firmware Target Count
00044 * @{
00045 */
00046 /**
00047 * Firmware target count for connector_request_id_firmware_count callback which
00048 * is called to return number of supported targets.
00049 */
00050 typedef struct {
00051     uint8_t count;             /**< Callback writes number of targets supported */
00052 } connector_firmware_count_t;
00053 /**
00054 * @}
00055 */
00056 
00057 /**
00058 * @defgroup connector_firmware_version_t Firmware Version n
00059 * @{
00060 */
00061 /**
00062 * Firmware version structure for @ref connector_request_id_firmware_info callback to return
00063 * the firmware version about the specific target.
00064 */
00065 typedef struct {
00066     uint8_t major;      /**< Major number */
00067     uint8_t minor;      /**< Minor number */
00068     uint8_t revision;   /**< revision number */
00069     uint8_t build;      /**< build number */
00070 } connector_firmware_version_t;
00071 /**
00072 * @}
00073 */
00074 
00075 /**
00076 * @defgroup connector_firmware_info_t Firmware Information
00077 * @{
00078 */
00079 /**
00080 * Firmware information structure for @ref connector_request_id_firmware_info callback to return
00081 * information about the specific target.
00082 */
00083 typedef struct {
00084 
00085     connector_firmware_version_t version; /**< Version number of the target */
00086     char const * description;   /**< An ASCII description string of the target */
00087     char const * filespec;      /**< Regular expression for the firmware image name for  the target */
00088 
00089     unsigned int CONST target_number; /**< Target number which target the firmware information is for*/
00090 } connector_firmware_info_t;
00091 /**
00092 * @}
00093 */
00094 
00095 /**
00096 * @defgroup connector_firmware_status_t Firmware Status Codes
00097 * @{
00098 */
00099 /**
00100 * Firmware status codes are used for @ref connector_request_id_firmware_download_start,
00101 * @see @ref connector_request_id_firmware_download_data and @ref connector_request_id_firmware_download_abort callbacks.
00102 */
00103 typedef enum {
00104    connector_firmware_status_success,                        /**< No error */
00105    connector_firmware_status_download_denied,                /**< Callback denied firmware update */
00106    connector_firmware_status_download_invalid_size,          /**< Callback returns invalid size */
00107    connector_firmware_status_download_invalid_version,       /**< Callback returns invalid version */
00108    connector_firmware_status_download_unauthenticated,       /**< Device Cloud has not been authenticated */
00109    connector_firmware_status_download_not_allowed,           /**< Device Cloud is not allowed to provided updates */
00110    connector_firmware_status_download_configured_to_reject,  /**< Callback rejects firmware update */
00111    connector_firmware_status_encountered_error,              /**< Callback encountered an error that precludes the firmware update */
00112    connector_firmware_status_user_abort,                     /**< User aborted firmware update */
00113    connector_firmware_status_device_error,                   /**< Device or Device Cloud encountered an error in the download data */
00114    connector_firmware_status_invalid_offset,                 /**< connector_request_id_firmware_download_data callback found invalid offset. */
00115    connector_firmware_status_invalid_data,                   /**< connector_request_id_firmware_download_data callback found invalid data block.*/
00116    connector_firmware_status_hardware_error                  /**< Callback found permanent hardware error */
00117 } connector_firmware_status_t;
00118 /**
00119 * @}
00120 */
00121 
00122 
00123 /**
00124 * @defgroup connector_fw_download_complete_status_t Firmware Complete Status Codes
00125 * @{
00126 */
00127 /**
00128 * Firmware Update Complete status codes are used in @see connector_firmware_download_complete callback.
00129 */
00130 typedef enum {
00131    connector_firmware_download_success,           /**< Callback returns this for firmware download finished successfully
00132                                                        and calculated checksum matched the checksum sent in the callback */
00133    connector_firmware_download_checksum_mismatch, /**< Callback returns this for download completed successfully, but
00134                                                        the calculated checksum did not match the checksum sent in the callback */
00135    connector_firmware_download_not_complete       /**< Callback did not complete download successfully */
00136 } connector_firmware_download_status_t;
00137 /**
00138 * @}
00139 */
00140 
00141 
00142 /**
00143 * @defgroup connector_firmware_download_start_t Firmware Download Start Structure
00144 * @{
00145 */
00146 /**
00147 * Firmware download start structure for @ref connector_request_id_firmware_download_start callback which
00148 * is called when the device is requested for firmware download.
00149 */
00150 typedef struct {
00151     unsigned int CONST target_number;   /**< Target number which firmware target the image data is for */
00152 
00153     char CONST * filename;              /**< Pointer to filename of the image to be downloaded */
00154 
00155     uint32_t code_size;                 /**< size of the code that is ready to be sent to the target */
00156 
00157     connector_firmware_status_t status; /**< Callback writes error status if error is encountered */
00158 
00159 } connector_firmware_download_start_t;
00160 /**
00161 * @}
00162 */
00163 
00164 
00165 /**
00166 * @defgroup connector_firmware_download_data_t Firmware Download Image Data Structure
00167 * @{
00168 */
00169 /**
00170 * Firmware download image data structure for connector_request_id_firmware_download_data callback which
00171 * is called when the connector receives a block of image data for firmware download.
00172 */
00173 typedef struct {
00174     unsigned int CONST target_number;  /**< Target number which firmware target the image data is for */
00175 
00176     struct {
00177         uint32_t CONST offset;    /**< Offset value where this particular block of image data fits into the download */
00178         uint8_t const * data;     /**< Pointer binary image data */
00179         size_t CONST bytes_used;  /**< Length of binary image data in bytes */
00180     } image;                      /**< Image data */
00181 
00182     connector_firmware_status_t status; /**< Callback writes error status if error is encountered */
00183 
00184 } connector_firmware_download_data_t;
00185 /**
00186 * @}
00187 */
00188 
00189 
00190 /**
00191 * @defgroup connector_firmware_download_complete_t Firmware Download Complete Structure
00192 * @{
00193 */
00194 /**
00195 * Firmware download complete structure containing information about firmware image data
00196 * for connector_request_id_firmware_download_complete callback which is called when Device Cloud is done
00197 * sending all image data.
00198 */
00199 typedef struct {
00200     unsigned int CONST target_number;  /**< Target number which firmware target the image data is for */
00201 
00202     connector_firmware_download_status_t status;     /**< Status code regarding the download completion */
00203 
00204 } connector_firmware_download_complete_t;
00205 /**
00206 * @}
00207 */
00208 
00209 
00210 /**
00211 * @defgroup connector_firmware_download_abort_t Firmware Download Abort Structure
00212 * @{
00213 */
00214 /**
00215 * Firmware download abort structure for connector_request_id_firmware_abort callback which
00216 * is called when firmware download process is aborted.
00217 */
00218 typedef struct {
00219     unsigned int CONST target_number;         /**< Target number which target the firmware download is aborted */
00220 
00221     connector_firmware_status_t CONST status; /**< Abort reason or status */
00222 } connector_firmware_download_abort_t;
00223 /**
00224 * @}
00225 */
00226 
00227 
00228 /**
00229 * @defgroup connector_firmware_reset_t Firmware Target Reset Structure
00230 * @{
00231 */
00232 /**
00233 * Firmware target reset structure for connector_request_id_firmware_reset callback which
00234 * is called to reset the target.
00235 */
00236 typedef struct {
00237     unsigned int CONST target_number;     /**< Target number which target the firmware to reset */
00238 } connector_firmware_reset_t;
00239 /**
00240 * @}
00241 */
00242 #endif
00243 
00244 #if !defined _CONNECTOR_API_H
00245 #error  "Illegal inclusion of connector_api_firmware.h. You should only include connector_api.h in user code."
00246 #endif
00247 
00248 #else
00249 #error  "Illegal inclusion of connector_api_firmware.h. You should only include connector_api.h in user code."
00250 #endif
00251 
00252