simple-mbed-cloud-client.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2018 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 SIMPLEMBEDCLOUDCLIENT_H
00020 #define SIMPLEMBEDCLOUDCLIENT_H
00021 #include <stdio.h>
00022 #include "mbed-cloud-client/MbedCloudClient.h"
00023 #include "m2mdevice.h"
00024 #include "m2mresource.h"
00025 #include "mbed-client/m2minterface.h"
00026 #include "mbed-client/m2mvector.h"
00027 #include "mbed-cloud-client-resource.h"
00028 #include "storage-helper/storage-helper.h"
00029 #include "mbed.h"
00030 #include "NetworkInterface.h"
00031 
00032 class MbedCloudClientResource;
00033 
00034 class SimpleMbedCloudClient {
00035 
00036 public:
00037 
00038     /**
00039      * Initialize SimpleMbedCloudClient
00040      *
00041      * @param net A connected network interface
00042      * @param bd An uninitialized block device to back the file system
00043      * @param fs An uninitialized file system
00044      */
00045     SimpleMbedCloudClient(NetworkInterface *net, BlockDevice *bd, FileSystem *fs);
00046 
00047     /**
00048      * SimpleMbedCloudClient destructor
00049      *
00050      * This deletes all managed resources
00051      * This does not unregister the client
00052      */
00053     ~SimpleMbedCloudClient();
00054 
00055     /**
00056      * Initialize SimpleMbedCloudClient
00057      *
00058      * Sets up factory configurator client, loads root of trust,
00059      * initializes storage, and loads existing developer credentials (if present)
00060      *
00061      * @param format If set to true, will always format the file system
00062      *
00063      * @returns 0 if successful, 1 if an error occured
00064      */
00065     int init(bool format = false);
00066 
00067     /**
00068      * Close the connection to Pelion Device Management and unregister the device
00069      */
00070     void close();
00071 
00072     /**
00073     * Sends a registration update message to the Cloud when the client is registered
00074     * successfully to the Cloud and there is no internal connection error.
00075     * If the client is not connected and there is some other internal network
00076     * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.
00077     */
00078     void register_update();
00079 
00080     /**
00081      * Checks registration status
00082      *
00083      * @returns true when connected, false when not connected
00084      */
00085     bool is_client_registered();
00086 
00087     /**
00088      * Whether the device has ever tried registering
00089      *
00090      * @returns true when registration was tried, false when not
00091      */
00092     bool is_register_called();
00093 
00094     /**
00095      * Register with Pelion Device Management
00096      * This does *not* initialize the MbedCloudClientResource added through SimpleMbedCloudClient
00097      * Only call this function after you unregistered first, do NOT use it to register the first time
00098      *
00099      * This function returns immediately, observe on_registered and on_error for updates.
00100      *
00101      * @returns true if connection started, false if connection was not started
00102      */
00103     bool call_register();
00104 
00105     /**
00106      * Create MbedCloudClientResource on the underlying Mbed Cloud Client object,
00107      * register with Pelion Device Management.
00108      *
00109      * This function can only be called once. If you need to re-register,
00110      * use `call_register`.
00111      *
00112      * This function returns immediately, observe the on_registered and
00113      * on_error callbacks for updates.
00114      *
00115      * @returns true if registration was started, false if registration was not started
00116      */
00117     bool register_and_connect();
00118 
00119     /**
00120      * Get the underlying Mbed Cloud Client
00121      */
00122     MbedCloudClient *get_cloud_client();
00123 
00124     /**
00125      * Create a new resource
00126      *
00127      * This does not add the resource to Mbed Cloud Client until `register_and_connect`
00128      * is called.
00129      * Resources need to be added before first registration.
00130      *
00131      * @param path LwM2M path (in the form of 3200/0/5501)
00132      * @param name Name of the resource (will be shown in the UI)
00133      *
00134      * @returns new instance of MbedCloudClientResource
00135      */
00136     MbedCloudClientResource* create_resource(const char *path, const char *name);
00137 
00138     /**
00139      * Sets the on_registered callback
00140      * This callback is fired when the device is registered with Pelion Device Management
00141      *
00142      * @param cb Callback
00143      */
00144     void on_registered(Callback<void(const ConnectorClientEndpointInfo*)> cb);
00145 
00146     /**
00147      * Sets the on_unregistered callback
00148      * This callback is fired when the device is unregistered with Pelion Device Management
00149      *
00150      * @param cb Callback
00151      */
00152     void on_unregistered(Callback<void()> cb);
00153 
00154     /**
00155      * Sets the update authorization callback
00156      * This will overwrite the default authorization callback (and thus the logging)
00157      *
00158      * @todo, replace this with Callback<>
00159      *
00160      * @param cb Callback
00161      */
00162     void on_update_authorized(void (*cb)(int32_t request));
00163 
00164     /**
00165      * Sets the update authorization callback
00166      * This will overwrite the default authorization callback (and thus the logging)
00167      *
00168      * @todo, replace this with Callback<>
00169      *
00170      * @param cb Callback
00171      */
00172     void on_update_progress(void (*cb)(uint32_t progress, uint32_t total));
00173 
00174     /**
00175      * Sets the error callback
00176      * This will overwrite the default error logging
00177      *
00178      * @param cb Callback
00179      */
00180     void on_error_cb(Callback<void(int, const char*)> cb);
00181 
00182     /**
00183      * Format the underlying storage
00184      *
00185      * returns 0 if successful, non-0 if failed
00186      */
00187     int reformat_storage();
00188 
00189 private:
00190 
00191     /**
00192      * Callback from Mbed Cloud Client, fires when device is registered
00193      */
00194     void client_registered();
00195 
00196     /**
00197      * Callback from Mbed Cloud Client, fires when device is unregistered
00198      */
00199     void client_unregistered();
00200 
00201     /**
00202      * Callback from Mbed Cloud Client, fires when error has occured
00203      */
00204     void error(int error_code);
00205 
00206     /**
00207      * Re-mount and re-format the storage layer
00208      *
00209      * @returns 0 if successful, non-0 if not successful
00210      */
00211     int reset_storage();
00212 
00213     /**
00214      * Retrigger the developer or FCC flow
00215      *
00216      * @param format If set to true, will first format the storage layer
00217      *
00218      * @returns 0 if successful, non-0 if not succesful
00219      */
00220     int verify_cloud_configuration(bool format);
00221 
00222     M2MObjectList                                       _obj_list;
00223     MbedCloudClient                                     _cloud_client;
00224     bool                                                _registered;
00225     bool                                                _register_called;
00226     bool                                                _register_and_connect_called;
00227     Vector<MbedCloudClientResource*>                    _resources;
00228     Callback<void(const ConnectorClientEndpointInfo*)>  _registered_cb;
00229     Callback<void()>                                    _unregistered_cb;
00230     Callback<void(int, const char*)>                    _error_cb;
00231     NetworkInterface *                                  _net;
00232     BlockDevice *                                       _bd;
00233     FileSystem *                                        _fs;
00234     StorageHelper                                       _storage;
00235 };
00236 
00237 #endif // SIMPLEMBEDCLOUDCLIENT_H