arm_uc_control_center.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef ARM_UPDATE_CONTROL_CENTER_H
00020 #define ARM_UPDATE_CONTROL_CENTER_H
00021 
00022 #include "update-client-monitor/arm_uc_monitor.h"
00023 #include "update-client-common/arm_uc_common.h"
00024 
00025 #include <stdint.h>
00026 
00027 typedef enum {
00028     ARM_UCCC_EVENT_AUTHORIZE_DOWNLOAD,
00029     ARM_UCCC_EVENT_AUTHORIZE_INSTALL,
00030     ARM_UCCC_EVENT_MONITOR_SEND_DONE,
00031 } arm_uc_contro_center_event_t;
00032 
00033 /**
00034  * @brief Initialize Control Center.
00035  *
00036  * @param callback Event handler to signal authorizations.
00037  * @return Error code.
00038  */
00039 arm_uc_error_t ARM_UC_ControlCenter_Initialize(void (*callback)(uint32_t));
00040 
00041 /**
00042  * @brief Add monitor struct for sending status and results remotely.
00043  * @details Update Client call for adding remote monitor.
00044  *
00045  * @param monitor Pointer to an ARM_UPDATE_MONITOR struct.
00046  * @return Error code.
00047  */
00048 arm_uc_error_t ARM_UC_ControlCenter_AddMonitor(const ARM_UPDATE_MONITOR* monitor);
00049 
00050 /**
00051  * @brief Set callback for receiving download progress.
00052  * @details User application call for setting callback handler.
00053  *          The callback function takes the progreess in percent as argument.
00054  *
00055  * @param callback Function pointer to the progress function.
00056  * @return Error code.
00057  */
00058 arm_uc_error_t ARM_UC_ControlCenter_SetProgressHandler(void (*callback)(uint32_t progress, uint32_t total));
00059 
00060 /**
00061  * @brief Set callback function for authorizing requests.
00062  * @details User application call for setting callback handler.
00063  *          The callback function takes an enum request and an authorization
00064  *          function pointer. To authorize the given request, the caller
00065  *          invokes the authorization function.
00066  *
00067  * @param callback Function pointer to the authorization function.
00068  * @return Error code.
00069  */
00070 arm_uc_error_t ARM_UC_ControlCenter_SetAuthorityHandler(void (*callback)(int32_t));
00071 
00072 /**
00073  * @brief Request authorization from Control Center.
00074  * @details Update Client call for asking user application for permission.
00075  *
00076  * @param type Request type.
00077  * @return Error code.
00078  */
00079 arm_uc_error_t ARM_UC_ControlCenter_GetAuthorization(arm_uc_request_t request);
00080 
00081 /**
00082  * @brief Authorize request.
00083  * @details User application call for authorizing request.
00084  *
00085  * @param request Request type. Must match the type in callback function.
00086  */
00087 arm_uc_error_t ARM_UC_ControlCenter_Authorize(arm_uc_request_t request);
00088 
00089 /**
00090  * @brief Override update authorization handler.
00091  * @details Force download and update to progress regardless of authorization
00092  *          handler. This function is used for unblocking an update in a buggy
00093  *          application.
00094  */
00095 void ARM_UC_ControlCenter_OverrideAuthorization(void);
00096 
00097 /**
00098  * @brief Report download progress.
00099  * @details Update Client call for informing the Control Center about the
00100  *          current download progress. The Control Center will send this to the
00101  *          appication handler and the monitor if either/both are attached.
00102  *
00103  * @param progress Bytes already downloaded.
00104  * @param total Total bytes in download.
00105  * @return Error code.
00106  */
00107 arm_uc_error_t ARM_UC_ControlCenter_ReportProgress(uint32_t progress, uint32_t total);
00108 
00109 /**
00110  * @brief Send Update Client state.
00111  * @details Update Client call for informing the Control Center about the
00112  *          current state. The Control Center will send this to the monitor.
00113  *
00114  *          From the OMA LWM2M Technical Specification:
00115  *
00116  *          Indicates current state with respect to this firmware update.
00117  *          This value is set by the LWM2M Client.
00118  *          0: Idle (before downloading or after successful updating)
00119  *          1: Downloading (The data sequence is on the way)
00120  *          2: Downloaded
00121  *          3: Updating
00122  *
00123  *          If writing the firmware package to Package Resource is done,
00124  *          or, if the device has downloaded the firmware package from the
00125  *          Package URI the state changes to Downloaded.
00126  *
00127  *          If writing an empty string to Package Resource is done or
00128  *          writing an empty string to Package URI is done, the state
00129  *          changes to Idle.
00130  *
00131  *          When in Downloaded state, and the executable Resource Update is
00132  *          triggered, the state changes to Updating.
00133  *          If the Update Resource failed, the state returns at Downloaded.
00134  *          If performing the Update Resource was successful, the state
00135  *          changes from Updating to Idle.
00136  *
00137  * @param state Valid states: ARM_UC_MONITOR_STATE_IDLE
00138  *                            ARM_UC_MONITOR_STATE_DOWNLOADING
00139  *                            ARM_UC_MONITOR_STATE_DOWNLOADED
00140  *                            ARM_UC_MONITOR_STATE_UPDATING
00141  *
00142  * @return Error code.
00143  */
00144 arm_uc_error_t ARM_UC_ControlCenter_ReportState(arm_uc_monitor_state_t state);
00145 
00146 /**
00147  * @brief Set update result.
00148  * @details Update Client call for informing the Control Center about the
00149  *          latest update result. The Control Center will send this to the monitor.
00150  *
00151  *          From the OMA LWM2M Technical Specification:
00152  *
00153  *          Contains the result of downloading or updating the firmware
00154  *          0: Initial value. Once the updating process is initiated
00155  *             (Download /Update), this Resource MUST be reset to Initial
00156  *             value.
00157  *          1: Firmware updated successfully,
00158  *          2: Not enough storage for the new firmware package.
00159  *          3. Out of memory during downloading process.
00160  *          4: Connection lost during downloading process.
00161  *          5: CRC check failure for new downloaded package.
00162  *          6: Unsupported package type.
00163  *          7: Invalid URI
00164  *          8: Firmware update failed
00165  *
00166  *          This Resource MAY be reported by sending Observe operation.
00167  *
00168  * @param result Valid results: ARM_UC_MONITOR_RESULT_INITIAL
00169  *                              ARM_UC_MONITOR_RESULT_SUCCESS
00170  *                              ARM_UC_MONITOR_RESULT_ERROR_STORAGE
00171  *                              ARM_UC_MONITOR_RESULT_ERROR_MEMORY
00172  *                              ARM_UC_MONITOR_RESULT_ERROR_CONNECTION
00173  *                              ARM_UC_MONITOR_RESULT_ERROR_CRC
00174  *                              ARM_UC_MONITOR_RESULT_ERROR_TYPE
00175  *                              ARM_UC_MONITOR_RESULT_ERROR_URI
00176  *                              ARM_UC_MONITOR_RESULT_ERROR_UPDATE
00177  *                              ARM_UC_MONITOR_RESULT_ERROR_HASH
00178  *
00179  * @return Error code.
00180  */
00181 arm_uc_error_t ARM_UC_ControlCenter_ReportUpdateResult(arm_uc_monitor_result_t updateResult);
00182 
00183 /**
00184  * @brief Set current firmware name.
00185  * @details Update Client call for informing the Control Center about the
00186  *          current firmware name. The Control Center will send this to the
00187  *          monitor. The firmware name is the SHA256 hash.
00188  *
00189  * @param name Pointer to buffer struct. Hash is stored as byte array.
00190  * @return Error code.
00191  */
00192 arm_uc_error_t ARM_UC_ControlCenter_ReportName(arm_uc_buffer_t* name);
00193 
00194 /**
00195  * @brief Set current firmware version.
00196  * @details Update Client call for informing the Control Center about the
00197  *          current firmware version. The Control Center will send this to the
00198  *          monitor. The firmware version is the manifest timestamp that
00199  *          authorized the installation.
00200  *
00201  * @param version Timestamp, 64 bit unsigned integer.
00202  * @return Error code.
00203  */
00204 arm_uc_error_t ARM_UC_ControlCenter_ReportVersion(uint64_t version);
00205 
00206 /**
00207  * @brief Send bootloader hash to monitor.
00208  * @details The bootloader hash is a hash of the bootloader. This is
00209  *          used for tracking the version of the bootloader used.
00210  *
00211  * @param name Pointer to buffer struct. Hash is stored as byte array.
00212  * @return Error code.
00213  */
00214 arm_uc_error_t ARM_UC_ControlCenter_ReportBootloaderHash(arm_uc_buffer_t* hash);
00215 
00216 /**
00217  * @brief Send the OEM bootloader hash to monitor.
00218  * @details If the end-user has modified the bootloader the hash of the
00219  *          modified bootloader can be set here.
00220  *
00221  * @param name Pointer to buffer struct. Hash is stored as byte array.
00222  * @return Error code.
00223  */
00224 arm_uc_error_t ARM_UC_ControlCenter_ReportOEMBootloaderHash(arm_uc_buffer_t* hash);
00225 
00226 #endif // __ARM_UPDATE_CONTROL_CENTER_H__
00227 
00228