Ram Gandikota / Mbed OS IOTMetronome

FRDM K64F Metronome

mbed-client/docs/porting-guide.md@0:dbad57390bd1, 2017-05-14 (annotated)

Committer:
ram54288
Date:
Sun May 14 18:37:05 2017 +0000
Revision:
0:dbad57390bd1
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ram54288 0:dbad57390bd1 1 <span class="notes">**Note:** To port mbed Client, you need to [install yotta and its dependencies](https://github.com/ARMmbed/yotta/blob/master/docs/index.md).</span>
ram54288 0:dbad57390bd1 2
ram54288 0:dbad57390bd1 3 # mbed Client structure and build process
ram54288 0:dbad57390bd1 4
ram54288 0:dbad57390bd1 5 <span class="tips">**Tip:** Before embarking on your own port, you should build the core mbed Client for an existing compilation target to get an understanding of how the mbed Client builds.</span>
ram54288 0:dbad57390bd1 6
ram54288 0:dbad57390bd1 7 mbed Client is structured as a set of modules. Each module declares which other modules it depends on. When you build a module, our build system `yotta` looks at these dependencies and installs the necessary modules before completing the build.
ram54288 0:dbad57390bd1 8
ram54288 0:dbad57390bd1 9 This is also the process to build applications for the mbed Client (including the example application in the release). The application declares dependencies on the mbed Client and when it is built, `yotta` ensures that the modules (and anything that they depend on, recursively) are present before building.
ram54288 0:dbad57390bd1 10
ram54288 0:dbad57390bd1 11 In general, `yotta` downloads and installs the necessary modules over the internet from the public yotta Registry (which saves published versions of modules) or from a specified source control URL.
ram54288 0:dbad57390bd1 12
ram54288 0:dbad57390bd1 13 # Components of mbed Client
ram54288 0:dbad57390bd1 14
ram54288 0:dbad57390bd1 15 ## Component software modules
ram54288 0:dbad57390bd1 16
ram54288 0:dbad57390bd1 17 mbed Client consists of one main component. More major components will be added in future development phases:
ram54288 0:dbad57390bd1 18
ram54288 0:dbad57390bd1 19 * `mbed-client` is the core mbed Client, providing C++ APIs for the mbed Client.
ram54288 0:dbad57390bd1 20
ram54288 0:dbad57390bd1 21 This module depends on further internal modules:
ram54288 0:dbad57390bd1 22
ram54288 0:dbad57390bd1 23 ```
ram54288 0:dbad57390bd1 24 mbed-client x.x.x
ram54288 0:dbad57390bd1 25 |
ram54288 0:dbad57390bd1 26 |_mbed-client-c x.x.x
ram54288 0:dbad57390bd1 27 | |_mbed-client-libservice x.x.x
ram54288 0:dbad57390bd1 28 |
ram54288 0:dbad57390bd1 29 |_mbed-client-linux x.x.x
ram54288 0:dbad57390bd1 30 ```
ram54288 0:dbad57390bd1 31
ram54288 0:dbad57390bd1 32 To list the dependency trees, use the [`yotta list --all` command](http://docs.yottabuild.org/reference/commands.html).
ram54288 0:dbad57390bd1 33
ram54288 0:dbad57390bd1 34 <span class="notes">**Note**: In this case, we have listed the dependencies for the `x86-linux-native` compilation target. Different modules are needed for different compilation targets.</span>
ram54288 0:dbad57390bd1 35
ram54288 0:dbad57390bd1 36 We are using the [mbed Client Linux example](https://github.com/ARMmbed/mbed-client-linux-example) in this document. You can see that it depends directly only on the `mbed-client` and `mbed-client-linux` modules. These modules depend internally on various other modules.
ram54288 0:dbad57390bd1 37
ram54288 0:dbad57390bd1 38 ```
ram54288 0:dbad57390bd1 39 mbed-client-linux-example x.x.x
ram54288 0:dbad57390bd1 40 |
ram54288 0:dbad57390bd1 41 |_mbed-client x.x.x
ram54288 0:dbad57390bd1 42 |
ram54288 0:dbad57390bd1 43 |_mbed-client-c x.x.x
ram54288 0:dbad57390bd1 44 | |_mbed-client-libservice x.x.x
ram54288 0:dbad57390bd1 45 |
ram54288 0:dbad57390bd1 46 |_mbed-client-linux x.x.x
ram54288 0:dbad57390bd1 47 ```
ram54288 0:dbad57390bd1 48
ram54288 0:dbad57390bd1 49 ## Compilation targets
ram54288 0:dbad57390bd1 50
ram54288 0:dbad57390bd1 51 To compile for a target board, you need a [target description](http://docs.yottabuild.org/tutorial/targets.html) that describes how to compile for the target.
ram54288 0:dbad57390bd1 52
ram54288 0:dbad57390bd1 53 The `mbed-client` module uses the platform name that each target defines to choose which `mbed-client-<platform-name>` module to depend on to provide the platform-specific implementation.
ram54288 0:dbad57390bd1 54
ram54288 0:dbad57390bd1 55 # Porting mbed Client to a different platform
ram54288 0:dbad57390bd1 56
ram54288 0:dbad57390bd1 57 To port mbed Client to a new platform:
ram54288 0:dbad57390bd1 58
ram54288 0:dbad57390bd1 59 1. [Request for a development repository](#requesting-for-a-development-repository).
ram54288 0:dbad57390bd1 60 2. [Create a yotta compilation target for your board](#creating-a-yotta-compilation-target).
ram54288 0:dbad57390bd1 61 3. [Implement the `mbed-client-xxx` module for your target platform](#implementing-mbed-client-xxx).
ram54288 0:dbad57390bd1 62 4. [Modify the `module.json` of the `mbed-client` module](#modifying-the-json-file-in-the-mbed-client-module).
ram54288 0:dbad57390bd1 63 5. [Verify that your implementation is correct](#testing-and-verification).
ram54288 0:dbad57390bd1 64
ram54288 0:dbad57390bd1 65 The `yotta` build system is designed for easy reuse of generic modules. If you intend to support multiple platforms that share common features, we recommend moving the common functionality into a separate module and use it for each platform.
ram54288 0:dbad57390bd1 66
ram54288 0:dbad57390bd1 67 ## Requesting for a development repository
ram54288 0:dbad57390bd1 68
ram54288 0:dbad57390bd1 69 We provide private git repositories to our partners porting mbed Client. Only the members of the mbed Client team and relevant partner contacts and engineers have access to these repositories.
ram54288 0:dbad57390bd1 70
ram54288 0:dbad57390bd1 71 When you contact `support@mbed.org`, a repository will be created for your module. You also need to provide the target description of your board as follows:
ram54288 0:dbad57390bd1 72
ram54288 0:dbad57390bd1 73 - **`mbed-client-<platform-name>`** is the module that provides the `mbed-client-xxx` implementation for your platform. You may choose to split it into further modules in the future, to enable sharing of code, but we recommend that you implement the port for your first board in this module itself.
ram54288 0:dbad57390bd1 74
ram54288 0:dbad57390bd1 75 - **`target-<targetname>`** contains the yotta target description of the target you are porting to. This is usually your platform name.
ram54288 0:dbad57390bd1 76
ram54288 0:dbad57390bd1 77 ## Creating a yotta compilation target
ram54288 0:dbad57390bd1 78
ram54288 0:dbad57390bd1 79 An example on compiling for linux target can be found in the `yotta_targets` directory of [the example application] (https://github.com/ARMmbed/mbed-client-linux-example).
ram54288 0:dbad57390bd1 80
ram54288 0:dbad57390bd1 81 Please, refer to the [yotta documentation](http://yottadocs.mbed.com/tutorial/targets.html) for setting up your compilation target.
ram54288 0:dbad57390bd1 82
ram54288 0:dbad57390bd1 83 1.To make your target available locally (without publishing it), you use the `yotta link-target` command to link it into the global install targets directory:
ram54288 0:dbad57390bd1 84
ram54288 0:dbad57390bd1 85 ```
ram54288 0:dbad57390bd1 86 # in the directory of your target:
ram54288 0:dbad57390bd1 87 yotta link-target
ram54288 0:dbad57390bd1 88 ```
ram54288 0:dbad57390bd1 89
ram54288 0:dbad57390bd1 90 2.Use `yotta link-target <targetname>` command to make the globally linked target available when compiling another module.
ram54288 0:dbad57390bd1 91
ram54288 0:dbad57390bd1 92 3.Use the `yotta target <targetname>` command to select your target for the compilation.
ram54288 0:dbad57390bd1 93
ram54288 0:dbad57390bd1 94 ## Implementing mbed-client-xxx
ram54288 0:dbad57390bd1 95
ram54288 0:dbad57390bd1 96 Clone your `mbed-client-<your-platform-name>` module and `mbed-client` modules from GitHub.
ram54288 0:dbad57390bd1 97
ram54288 0:dbad57390bd1 98 The `mbed-client-<your-platform-name>` module needs to provide a socket and timer implementation for your target platform. The `mbed-client-xxx` module should include files `m2mconnectionhandler.h`and `m2mtimer.h` from `mbed-client` and implement a corresponding `.cpp` file that points to the platform-specific private implementations of the timer and the socket.
ram54288 0:dbad57390bd1 99
ram54288 0:dbad57390bd1 100 <span class="notes">**Note**: Private implementation classes **must** be named as `M2MConnectionHandlerPimpl` and `M2MTimerPimpl`, because of forward declarations.</span>
ram54288 0:dbad57390bd1 101
ram54288 0:dbad57390bd1 102 An example of mbed-client-platform:
ram54288 0:dbad57390bd1 103
ram54288 0:dbad57390bd1 104 ```
ram54288 0:dbad57390bd1 105 |_module.json
ram54288 0:dbad57390bd1 106 |
ram54288 0:dbad57390bd1 107 |_mbed-client-platform
ram54288 0:dbad57390bd1 108 | |_m2mconnectionhandlerpimpl.h
ram54288 0:dbad57390bd1 109 | |_m2mtimerpimpl.h
ram54288 0:dbad57390bd1 110 |
ram54288 0:dbad57390bd1 111 |_source
ram54288 0:dbad57390bd1 112 |_m2mconnectionhandler.cpp
ram54288 0:dbad57390bd1 113 |_m2mconnectionhandlerpimpl.cpp
ram54288 0:dbad57390bd1 114 |_m2mtimer.cpp
ram54288 0:dbad57390bd1 115 |_m2mtimerpimpl.cpp
ram54288 0:dbad57390bd1 116 ```
ram54288 0:dbad57390bd1 117
ram54288 0:dbad57390bd1 118 To make your module available to other modules that you want to build, you need to use the [`yotta link`](http://docs.yottabuild.org/reference/commands.html#yotta-link) command to link it to the module where you want to test it out.
ram54288 0:dbad57390bd1 119
ram54288 0:dbad57390bd1 120 For example, to use your local your in-development mbed-client implementation, use the command `yotta link mbed-client-xxx` in the main `mbed-client` module.
ram54288 0:dbad57390bd1 121
ram54288 0:dbad57390bd1 122 ```
ram54288 0:dbad57390bd1 123 # in mbed-client, link your module:
ram54288 0:dbad57390bd1 124 yotta link mbed-client-xxx
ram54288 0:dbad57390bd1 125 ```
ram54288 0:dbad57390bd1 126
ram54288 0:dbad57390bd1 127 You can also just commit and push your untested code to GitHub, but it is always a good idea to test before committing.
ram54288 0:dbad57390bd1 128
ram54288 0:dbad57390bd1 129 Your `mbed-client-xxx` module must provide a platform-specific implementation for the mbed-client. The APIs that need porting are defined in the `mbed-client-linux` module. The header files contain documentation alongside the declaration of each function, where the function is described along with its parameters and return value.
ram54288 0:dbad57390bd1 130
ram54288 0:dbad57390bd1 131 There are two header files that require porting for your platform:
ram54288 0:dbad57390bd1 132
ram54288 0:dbad57390bd1 133 - `m2mconnectionhandler.h`
ram54288 0:dbad57390bd1 134 - `m2mtimer.h`
ram54288 0:dbad57390bd1 135
ram54288 0:dbad57390bd1 136 To see how this is done in Linux, check the `mbed-client-linux` module from the mbed [Client Linux Example](https://github.com/ARMmbed/mbed-client-linux-example).
ram54288 0:dbad57390bd1 137
ram54288 0:dbad57390bd1 138 ### Implementing the M2MConnectionHandler class for your platform
ram54288 0:dbad57390bd1 139
ram54288 0:dbad57390bd1 140 ```
ram54288 0:dbad57390bd1 141 /*
ram54288 0:dbad57390bd1 142 * Copyright (c) 2015 ARM. All rights reserved.
ram54288 0:dbad57390bd1 143 */
ram54288 0:dbad57390bd1 144 #ifndef M2M_CONNECTION_HANDLER_H__
ram54288 0:dbad57390bd1 145 #define M2M_CONNECTION_HANDLER_H__
ram54288 0:dbad57390bd1 146
ram54288 0:dbad57390bd1 147 #include "mbed-client/m2mconfig.h"
ram54288 0:dbad57390bd1 148 #include "mbed-client/m2minterface.h"
ram54288 0:dbad57390bd1 149 #include "mbed-client/m2mconnectionobserver.h"
ram54288 0:dbad57390bd1 150 #include "nsdl-c/sn_nsdl.h"
ram54288 0:dbad57390bd1 151
ram54288 0:dbad57390bd1 152 /**
ram54288 0:dbad57390bd1 153 * \brief M2MConnectionHandler.
ram54288 0:dbad57390bd1 154 * This class handles the socket connection for the LWM2M Client.
ram54288 0:dbad57390bd1 155 */
ram54288 0:dbad57390bd1 156
ram54288 0:dbad57390bd1 157 class M2MConnectionHandler {
ram54288 0:dbad57390bd1 158 public:
ram54288 0:dbad57390bd1 159
ram54288 0:dbad57390bd1 160 /**
ram54288 0:dbad57390bd1 161 * @enum ConnectionError
ram54288 0:dbad57390bd1 162 * This enum defines an error that can come from
ram54288 0:dbad57390bd1 163 * socket read and write operation.
ram54288 0:dbad57390bd1 164 */
ram54288 0:dbad57390bd1 165 typedef enum {
ram54288 0:dbad57390bd1 166 CONNECTION_ERROR_WANTS_READ = -1000,
ram54288 0:dbad57390bd1 167 CONNECTION_ERROR_WANTS_WRITE = -1001,
ram54288 0:dbad57390bd1 168 ERROR_NONE = 0,
ram54288 0:dbad57390bd1 169 SSL_CONNECTION_ERROR,
ram54288 0:dbad57390bd1 170 SOCKET_READ_ERROR,
ram54288 0:dbad57390bd1 171 SOCKET_SEND_ERROR,
ram54288 0:dbad57390bd1 172 SOCKET_ABORT,
ram54288 0:dbad57390bd1 173 DNS_RESOLVING_ERROR,
ram54288 0:dbad57390bd1 174 SSL_HANDSHAKE_ERROR
ram54288 0:dbad57390bd1 175 }ConnectionError;
ram54288 0:dbad57390bd1 176
ram54288 0:dbad57390bd1 177
ram54288 0:dbad57390bd1 178 public:
ram54288 0:dbad57390bd1 179
ram54288 0:dbad57390bd1 180 /**
ram54288 0:dbad57390bd1 181 * \brief Constructor
ram54288 0:dbad57390bd1 182 */
ram54288 0:dbad57390bd1 183 M2MConnectionHandler(M2MConnectionObserver &observer,
ram54288 0:dbad57390bd1 184 M2MConnectionSecurity* sec,
ram54288 0:dbad57390bd1 185 M2MInterface::BindingMode mode,
ram54288 0:dbad57390bd1 186 M2MInterface::NetworkStack stack);
ram54288 0:dbad57390bd1 187
ram54288 0:dbad57390bd1 188 /**
ram54288 0:dbad57390bd1 189 * \brief Destructor
ram54288 0:dbad57390bd1 190 */
ram54288 0:dbad57390bd1 191 ~M2MConnectionHandler();
ram54288 0:dbad57390bd1 192
ram54288 0:dbad57390bd1 193 /**
ram54288 0:dbad57390bd1 194 * \brief This binds the socket connection.
ram54288 0:dbad57390bd1 195 * \param listen_port Port to be listened to for an incoming connection.
ram54288 0:dbad57390bd1 196 * \return True if successful, else false.
ram54288 0:dbad57390bd1 197 */
ram54288 0:dbad57390bd1 198 bool bind_connection(const uint16_t listen_port);
ram54288 0:dbad57390bd1 199
ram54288 0:dbad57390bd1 200 /**
ram54288 0:dbad57390bd1 201 * \brief This resolves the server address. Output is
ram54288 0:dbad57390bd1 202 * returned through a callback.
ram54288 0:dbad57390bd1 203 * \param String The server address.
ram54288 0:dbad57390bd1 204 * \param uint16_t The server port.
ram54288 0:dbad57390bd1 205 * \param ServerType The server type to be resolved.
ram54288 0:dbad57390bd1 206 * \param security The M2MSecurity object that determines which
ram54288 0:dbad57390bd1 207 * type of secure connection will be used by the socket.
ram54288 0:dbad57390bd1 208 * \return True if address is valid, else false.
ram54288 0:dbad57390bd1 209 */
ram54288 0:dbad57390bd1 210 bool resolve_server_address(const String& server_address,
ram54288 0:dbad57390bd1 211 const uint16_t server_port,
ram54288 0:dbad57390bd1 212 M2MConnectionObserver::ServerType server_type,
ram54288 0:dbad57390bd1 213 const M2MSecurity* security);
ram54288 0:dbad57390bd1 214
ram54288 0:dbad57390bd1 215 /**
ram54288 0:dbad57390bd1 216 * \brief Sends data to the connected server.
ram54288 0:dbad57390bd1 217 * \param data_ptr The data to be sent.
ram54288 0:dbad57390bd1 218 * \param data_len The length of data to be sent.
ram54288 0:dbad57390bd1 219 * \param address_ptr The address structure to which the data needs to be sent.
ram54288 0:dbad57390bd1 220 * \return True if data is sent successfully, else false.
ram54288 0:dbad57390bd1 221 */
ram54288 0:dbad57390bd1 222 bool send_data(uint8_t *data_ptr,
ram54288 0:dbad57390bd1 223 uint16_t data_len,
ram54288 0:dbad57390bd1 224 sn_nsdl_addr_s *address_ptr);
ram54288 0:dbad57390bd1 225
ram54288 0:dbad57390bd1 226 /**
ram54288 0:dbad57390bd1 227 * \brief Listens to the incoming data from a remote server.
ram54288 0:dbad57390bd1 228 * \return True if successful, else false.
ram54288 0:dbad57390bd1 229 */
ram54288 0:dbad57390bd1 230 bool start_listening_for_data();
ram54288 0:dbad57390bd1 231
ram54288 0:dbad57390bd1 232 /**
ram54288 0:dbad57390bd1 233 * \brief Stops listening to the incoming data.
ram54288 0:dbad57390bd1 234 */
ram54288 0:dbad57390bd1 235 void stop_listening();
ram54288 0:dbad57390bd1 236
ram54288 0:dbad57390bd1 237 /**
ram54288 0:dbad57390bd1 238 * \brief Sends directly to the socket. This is used by
ram54288 0:dbad57390bd1 239 * security classes to send the data after it has been encrypted.
ram54288 0:dbad57390bd1 240 * \param buf Buffer to send.
ram54288 0:dbad57390bd1 241 * \param len The length of the buffer.
ram54288 0:dbad57390bd1 242 * \return Number of bytes sent or -1 if failed.
ram54288 0:dbad57390bd1 243 */
ram54288 0:dbad57390bd1 244 int send_to_socket(const unsigned char *buf, size_t len);
ram54288 0:dbad57390bd1 245
ram54288 0:dbad57390bd1 246 /**
ram54288 0:dbad57390bd1 247 * \brief Receives directly from the socket. This
ram54288 0:dbad57390bd1 248 * is used by the security classes to receive raw data to be decrypted.
ram54288 0:dbad57390bd1 249 * \param buf Buffer to send.
ram54288 0:dbad57390bd1 250 * \param len The length of the buffer.
ram54288 0:dbad57390bd1 251 * \return Number of bytes read or -1 if failed.
ram54288 0:dbad57390bd1 252 */
ram54288 0:dbad57390bd1 253 int receive_from_socket(unsigned char *buf, size_t len);
ram54288 0:dbad57390bd1 254
ram54288 0:dbad57390bd1 255 /**
ram54288 0:dbad57390bd1 256 * \brief Closes the open connection.
ram54288 0:dbad57390bd1 257 */
ram54288 0:dbad57390bd1 258 void close_connection();
ram54288 0:dbad57390bd1 259
ram54288 0:dbad57390bd1 260 /**
ram54288 0:dbad57390bd1 261 * \brief Error handling for DTLS connectivity.
ram54288 0:dbad57390bd1 262 * \param error Error code from the TLS library.
ram54288 0:dbad57390bd1 263 */
ram54288 0:dbad57390bd1 264 void handle_connection_error(int error);
ram54288 0:dbad57390bd1 265
ram54288 0:dbad57390bd1 266 /**
ram54288 0:dbad57390bd1 267 * \brief Sets the network interface handler that is used by client to connect
ram54288 0:dbad57390bd1 268 * to a network over IP..
ram54288 0:dbad57390bd1 269 * \param handler A network interface handler that is used by client to connect.
ram54288 0:dbad57390bd1 270 * This API is optional but provides a mechanism for different platforms to
ram54288 0:dbad57390bd1 271 * manage usage of underlying network interface by client.
ram54288 0:dbad57390bd1 272 */
ram54288 0:dbad57390bd1 273 void set_platform_network_handler(void *handler = NULL);
ram54288 0:dbad57390bd1 274
ram54288 0:dbad57390bd1 275 /**
ram54288 0:dbad57390bd1 276 * \brief Claims mutex to prevent thread clashes
ram54288 0:dbad57390bd1 277 * in multithreaded environment.
ram54288 0:dbad57390bd1 278 */
ram54288 0:dbad57390bd1 279 void claim_mutex();
ram54288 0:dbad57390bd1 280
ram54288 0:dbad57390bd1 281 /**
ram54288 0:dbad57390bd1 282 * \brief Releases mutex to prevent thread clashes
ram54288 0:dbad57390bd1 283 * in multithreaded environment.
ram54288 0:dbad57390bd1 284 */
ram54288 0:dbad57390bd1 285 void release_mutex();
ram54288 0:dbad57390bd1 286
ram54288 0:dbad57390bd1 287 private:
ram54288 0:dbad57390bd1 288
ram54288 0:dbad57390bd1 289 M2MConnectionObserver &_observer;
ram54288 0:dbad57390bd1 290 M2MConnectionHandlerPimpl *_private_impl;
ram54288 0:dbad57390bd1 291
ram54288 0:dbad57390bd1 292 friend class Test_M2MConnectionHandler;
ram54288 0:dbad57390bd1 293 friend class Test_M2MConnectionHandler_mbed;
ram54288 0:dbad57390bd1 294 friend class Test_M2MConnectionHandler_linux;
ram54288 0:dbad57390bd1 295 friend class M2MConnection_TestObserver;
ram54288 0:dbad57390bd1 296 };
ram54288 0:dbad57390bd1 297
ram54288 0:dbad57390bd1 298 #endif //M2M_CONNECTION_HANDLER_H__
ram54288 0:dbad57390bd1 299
ram54288 0:dbad57390bd1 300 ```
ram54288 0:dbad57390bd1 301
ram54288 0:dbad57390bd1 302 Please note that some of these functions are asynchronous in nature and some are expecting a callback from the network. For example, receiving data from a socket needs to be communicated back to `mbed-client` so that the library can act on the data received. The callback comes through the Observer class defined in `M2MConnectionObserver`.
ram54288 0:dbad57390bd1 303
ram54288 0:dbad57390bd1 304 The file `m2mconnectionobserver.h` is present in `mbed-client`. To see how the callback needs to be called, check the implementation in `m2mconnectionhandlerpimpl.cpp` in `mbed-client-linux`.
ram54288 0:dbad57390bd1 305
ram54288 0:dbad57390bd1 306 ```
ram54288 0:dbad57390bd1 307 /*
ram54288 0:dbad57390bd1 308 * Copyright (c) 2015 ARM. All rights reserved.
ram54288 0:dbad57390bd1 309 */
ram54288 0:dbad57390bd1 310 #ifndef M2M_CONNECTION_OBSERVER_H__
ram54288 0:dbad57390bd1 311 #define M2M_CONNECTION_OBSERVER_H__
ram54288 0:dbad57390bd1 312
ram54288 0:dbad57390bd1 313 #include "mbed-client/m2minterface.h"
ram54288 0:dbad57390bd1 314
ram54288 0:dbad57390bd1 315 /**
ram54288 0:dbad57390bd1 316 * @brief Observer class for informing socket activity to the state machine
ram54288 0:dbad57390bd1 317 */
ram54288 0:dbad57390bd1 318
ram54288 0:dbad57390bd1 319 class M2MConnectionObserver
ram54288 0:dbad57390bd1 320 {
ram54288 0:dbad57390bd1 321
ram54288 0:dbad57390bd1 322 public :
ram54288 0:dbad57390bd1 323
ram54288 0:dbad57390bd1 324 /**
ram54288 0:dbad57390bd1 325 * \enum ServerType, Defines the type of the
ram54288 0:dbad57390bd1 326 * server that the client wants to use.
ram54288 0:dbad57390bd1 327 */
ram54288 0:dbad57390bd1 328 typedef enum {
ram54288 0:dbad57390bd1 329 Bootstrap,
ram54288 0:dbad57390bd1 330 LWM2MServer
ram54288 0:dbad57390bd1 331 }ServerType;
ram54288 0:dbad57390bd1 332
ram54288 0:dbad57390bd1 333 /**
ram54288 0:dbad57390bd1 334 * \brief The M2MSocketAddress struct.
ram54288 0:dbad57390bd1 335 * Unified container for holding socket address data
ram54288 0:dbad57390bd1 336 * across different platforms.
ram54288 0:dbad57390bd1 337 */
ram54288 0:dbad57390bd1 338 struct SocketAddress{
ram54288 0:dbad57390bd1 339 M2MInterface::NetworkStack _stack;
ram54288 0:dbad57390bd1 340 void *_address;
ram54288 0:dbad57390bd1 341 uint8_t _length;
ram54288 0:dbad57390bd1 342 uint16_t _port;
ram54288 0:dbad57390bd1 343 };
ram54288 0:dbad57390bd1 344
ram54288 0:dbad57390bd1 345 /**
ram54288 0:dbad57390bd1 346 * \brief Indicates that data is available from socket.
ram54288 0:dbad57390bd1 347 * \param data The data read from the socket.
ram54288 0:dbad57390bd1 348 * \param data_size The length of the data read from the socket.
ram54288 0:dbad57390bd1 349 * \param address The address of the server where the data is coming from.
ram54288 0:dbad57390bd1 350 */
ram54288 0:dbad57390bd1 351 virtual void data_available(uint8_t* data,
ram54288 0:dbad57390bd1 352 uint16_t data_size,
ram54288 0:dbad57390bd1 353 const M2MConnectionObserver::SocketAddress &address) = 0;
ram54288 0:dbad57390bd1 354
ram54288 0:dbad57390bd1 355 /**
ram54288 0:dbad57390bd1 356 * \brief Indicates an error occured in socket.
ram54288 0:dbad57390bd1 357 * \param error_code The error code from socket, it cannot be used any further.
ram54288 0:dbad57390bd1 358 * \param retry Indicates whether to re-establish connection.
ram54288 0:dbad57390bd1 359 */
ram54288 0:dbad57390bd1 360 virtual void socket_error(uint8_t error_code, bool retry = true) = 0;
ram54288 0:dbad57390bd1 361
ram54288 0:dbad57390bd1 362 /**
ram54288 0:dbad57390bd1 363 * \brief Indicates that the server address resolving is ready.
ram54288 0:dbad57390bd1 364 * \param address The resolved socket address.
ram54288 0:dbad57390bd1 365 * \param server_type The type of the server.
ram54288 0:dbad57390bd1 366 * \param server_port The port of the resolved server address.
ram54288 0:dbad57390bd1 367 */
ram54288 0:dbad57390bd1 368 virtual void address_ready(const M2MConnectionObserver::SocketAddress &address,
ram54288 0:dbad57390bd1 369 M2MConnectionObserver::ServerType server_type,
ram54288 0:dbad57390bd1 370 const uint16_t server_port) = 0;
ram54288 0:dbad57390bd1 371
ram54288 0:dbad57390bd1 372 /**
ram54288 0:dbad57390bd1 373 * \brief Indicates that data has been sent successfully.
ram54288 0:dbad57390bd1 374 */
ram54288 0:dbad57390bd1 375 virtual void data_sent() = 0;
ram54288 0:dbad57390bd1 376 };
ram54288 0:dbad57390bd1 377
ram54288 0:dbad57390bd1 378 #endif // M2M_CONNECTION_OBSERVER_H__
ram54288 0:dbad57390bd1 379
ram54288 0:dbad57390bd1 380 ```
ram54288 0:dbad57390bd1 381
ram54288 0:dbad57390bd1 382 ### Implementing M2MTimer class for your platform
ram54288 0:dbad57390bd1 383
ram54288 0:dbad57390bd1 384 This class provides the periodic timer functionality for your platform.
ram54288 0:dbad57390bd1 385
ram54288 0:dbad57390bd1 386 ```
ram54288 0:dbad57390bd1 387 /*
ram54288 0:dbad57390bd1 388 * Copyright (c) 2015 ARM. All rights reserved.
ram54288 0:dbad57390bd1 389 */
ram54288 0:dbad57390bd1 390 #ifndef M2M_TIMER_H
ram54288 0:dbad57390bd1 391 #define M2M_TIMER_H
ram54288 0:dbad57390bd1 392
ram54288 0:dbad57390bd1 393 #include <stdint.h>
ram54288 0:dbad57390bd1 394
ram54288 0:dbad57390bd1 395 class M2MTimerObserver;
ram54288 0:dbad57390bd1 396 /**
ram54288 0:dbad57390bd1 397 * @brief M2MTimerImpl
ram54288 0:dbad57390bd1 398 * Private implementation class for timer, this can be
ram54288 0:dbad57390bd1 399 * modified based on the board on which mbed Client needs
ram54288 0:dbad57390bd1 400 * to be used.
ram54288 0:dbad57390bd1 401 */
ram54288 0:dbad57390bd1 402 class M2MTimerImpl
ram54288 0:dbad57390bd1 403 {
ram54288 0:dbad57390bd1 404 private:
ram54288 0:dbad57390bd1 405
ram54288 0:dbad57390bd1 406 // Prevents the use of assignment operator
ram54288 0:dbad57390bd1 407 M2MTimer& operator=(const M2MTimer& other);
ram54288 0:dbad57390bd1 408
ram54288 0:dbad57390bd1 409 // Prevents the use of copy constructor
ram54288 0:dbad57390bd1 410 M2MTimer(const M2MTimer& other);
ram54288 0:dbad57390bd1 411
ram54288 0:dbad57390bd1 412 public:
ram54288 0:dbad57390bd1 413
ram54288 0:dbad57390bd1 414 /**
ram54288 0:dbad57390bd1 415 * Constructor.
ram54288 0:dbad57390bd1 416 */
ram54288 0:dbad57390bd1 417 M2MTimer(M2MTimerObserver& _observer);
ram54288 0:dbad57390bd1 418
ram54288 0:dbad57390bd1 419 /**
ram54288 0:dbad57390bd1 420 * Destructor.
ram54288 0:dbad57390bd1 421 */
ram54288 0:dbad57390bd1 422 virtual ~M2MTimer();
ram54288 0:dbad57390bd1 423
ram54288 0:dbad57390bd1 424 /**
ram54288 0:dbad57390bd1 425 * Starts timer
ram54288 0:dbad57390bd1 426 * @param interval Timer's interval in milliseconds
ram54288 0:dbad57390bd1 427 * @param single_shot defines if timer is ticked
ram54288 0:dbad57390bd1 428 * once or is it restarted everytime timer expires.
ram54288 0:dbad57390bd1 429 */
ram54288 0:dbad57390bd1 430 void start_timer(uint64_t interval, bool single_shot = true);
ram54288 0:dbad57390bd1 431
ram54288 0:dbad57390bd1 432 /**
ram54288 0:dbad57390bd1 433 * @brief Starts timer in DTLS manner.
ram54288 0:dbad57390bd1 434 * @param intermediate_interval Intermediate interval to use, must be smaller than tiotal (usually 1/4 of total).
ram54288 0:dbad57390bd1 435 * @param total_interval Total interval to use, this is the timeout value of a DTLS packet.
ram54288 0:dbad57390bd1 436 * @param type Type of the timer
ram54288 0:dbad57390bd1 437 */
ram54288 0:dbad57390bd1 438 void start_dtls_timer(uint64_t intermediate_interval, uint64_t total_interval,
ram54288 0:dbad57390bd1 439 M2MTimerObserver::Type type = M2MTimerObserver::Dtls);
ram54288 0:dbad57390bd1 440
ram54288 0:dbad57390bd1 441 /**
ram54288 0:dbad57390bd1 442 * Stops timer.
ram54288 0:dbad57390bd1 443 * This cancels the ongoing timer.
ram54288 0:dbad57390bd1 444 */
ram54288 0:dbad57390bd1 445 void stop_timer();
ram54288 0:dbad57390bd1 446
ram54288 0:dbad57390bd1 447 /**
ram54288 0:dbad57390bd1 448 * @brief Checks if the intermediate interval has passed.
ram54288 0:dbad57390bd1 449 * @return true if interval has passed, false otherwise.
ram54288 0:dbad57390bd1 450 */
ram54288 0:dbad57390bd1 451 bool is_intermediate_interval_passed();
ram54288 0:dbad57390bd1 452
ram54288 0:dbad57390bd1 453 /**
ram54288 0:dbad57390bd1 454 * @brief Checks if the total interval has passed.
ram54288 0:dbad57390bd1 455 * @return true if interval has passed, false otherwise.
ram54288 0:dbad57390bd1 456 */
ram54288 0:dbad57390bd1 457 bool is_total_interval_passed();
ram54288 0:dbad57390bd1 458
ram54288 0:dbad57390bd1 459 };
ram54288 0:dbad57390bd1 460
ram54288 0:dbad57390bd1 461 #endif // M2M_TIMER_H
ram54288 0:dbad57390bd1 462 ```
ram54288 0:dbad57390bd1 463
ram54288 0:dbad57390bd1 464 The timer API functions are asynchronous in nature and whenever a timer event is available, `mbed-client` is notified, so that the library can act on the _timer expired_ signal. The callback is received through an Observer class defined in `M2MTimerObserver` .
ram54288 0:dbad57390bd1 465
ram54288 0:dbad57390bd1 466 The file `m2mtimerobserver.h` is present in `mbed-client`. To see how the callback needs to be called, check the implementation in `m2mtimerimpl.cpp` in `mbed-client-linux`.
ram54288 0:dbad57390bd1 467
ram54288 0:dbad57390bd1 468 ```
ram54288 0:dbad57390bd1 469 /*
ram54288 0:dbad57390bd1 470 * Copyright (c) 2015 ARM. All rights reserved.
ram54288 0:dbad57390bd1 471 */
ram54288 0:dbad57390bd1 472 #ifndef M2M_TIMER_OBSERVER_H
ram54288 0:dbad57390bd1 473 #define M2M_TIMER_OBSERVER_H
ram54288 0:dbad57390bd1 474
ram54288 0:dbad57390bd1 475 /**
ram54288 0:dbad57390bd1 476 * Observer class for informing the parent class of the timer expiry.
ram54288 0:dbad57390bd1 477 */
ram54288 0:dbad57390bd1 478 class M2MTimerObserver
ram54288 0:dbad57390bd1 479 {
ram54288 0:dbad57390bd1 480 public:
ram54288 0:dbad57390bd1 481 /**
ram54288 0:dbad57390bd1 482 * \enum Defines the types of timer
ram54288 0:dbad57390bd1 483 * that can be created for mbed Client.
ram54288 0:dbad57390bd1 484 */
ram54288 0:dbad57390bd1 485 typedef enum {
ram54288 0:dbad57390bd1 486 Notdefined,
ram54288 0:dbad57390bd1 487 Registration,
ram54288 0:dbad57390bd1 488 NsdlExecution,
ram54288 0:dbad57390bd1 489 PMinTimer,
ram54288 0:dbad57390bd1 490 PMaxTimer,
ram54288 0:dbad57390bd1 491 Dtls,
ram54288 0:dbad57390bd1 492 QueueSleep,
ram54288 0:dbad57390bd1 493 RetryTimer
ram54288 0:dbad57390bd1 494 }Type;
ram54288 0:dbad57390bd1 495
ram54288 0:dbad57390bd1 496 /**
ram54288 0:dbad57390bd1 497 * \brief Indicates that the timer has expired.
ram54288 0:dbad57390bd1 498 * \param type The type of the timer that has expired.
ram54288 0:dbad57390bd1 499 */
ram54288 0:dbad57390bd1 500 virtual void timer_expired(M2MTimerObserver::Type type =
ram54288 0:dbad57390bd1 501 M2MTimerObserver::Notdefined) = 0;
ram54288 0:dbad57390bd1 502 };
ram54288 0:dbad57390bd1 503
ram54288 0:dbad57390bd1 504 #endif // M2M_TIMER_OBSERVER_H
ram54288 0:dbad57390bd1 505 ```
ram54288 0:dbad57390bd1 506
ram54288 0:dbad57390bd1 507 ## Modifying the `json` file in the `mbed-client` module
ram54288 0:dbad57390bd1 508
ram54288 0:dbad57390bd1 509 You need to add your target name to `module.json` so that when you set `yt target <platform>`, yotta can resolve the dependency correctly and link the main library with your module.
ram54288 0:dbad57390bd1 510
ram54288 0:dbad57390bd1 511 Two platforms, mbed OS and Linux, are already supported. You just need to add your module support after that.
ram54288 0:dbad57390bd1 512
ram54288 0:dbad57390bd1 513 ```
ram54288 0:dbad57390bd1 514 {
ram54288 0:dbad57390bd1 515 "name": "mbed-client",
ram54288 0:dbad57390bd1 516 "version": "1.12.0",
ram54288 0:dbad57390bd1 517 "description": "Mbed Client API",
ram54288 0:dbad57390bd1 518 "private": true,
ram54288 0:dbad57390bd1 519 "keywords": [],
ram54288 0:dbad57390bd1 520 "author": "XXX XXX <xxx.xxx@xxx.com>",
ram54288 0:dbad57390bd1 521 "homepage": "https://github.com/ARMmbed/mbed-client",
ram54288 0:dbad57390bd1 522 "licenses": [
ram54288 0:dbad57390bd1 523 {
ram54288 0:dbad57390bd1 524 "url": "https://spdx.org/licenses/Apache-2.0",
ram54288 0:dbad57390bd1 525 "type": "Apache-2.0"
ram54288 0:dbad57390bd1 526 }
ram54288 0:dbad57390bd1 527 ],
ram54288 0:dbad57390bd1 528 "dependencies": {
ram54288 0:dbad57390bd1 529 "mbed-client-c": "^2.0.0"
ram54288 0:dbad57390bd1 530 },
ram54288 0:dbad57390bd1 531 "targetDependencies": {
ram54288 0:dbad57390bd1 532 "arm": {
ram54288 0:dbad57390bd1 533 "mbed-client-mbed": "^3.0.0"
ram54288 0:dbad57390bd1 534 },
ram54288 0:dbad57390bd1 535 "linux": {
ram54288 0:dbad57390bd1 536 "mbed-client-linux": "^3.0.0"
ram54288 0:dbad57390bd1 537 },
ram54288 0:dbad57390bd1 538 "<your platform as defined in target.json>" : {
ram54288 0:dbad57390bd1 539 "mbed-client-platform": "<published version , can be done later, first link locally as explained in the steps above>"
ram54288 0:dbad57390bd1 540 },
ram54288 0:dbad57390bd1 541 }
ram54288 0:dbad57390bd1 542 }
ram54288 0:dbad57390bd1 543 ```
ram54288 0:dbad57390bd1 544
ram54288 0:dbad57390bd1 545 ## Testing and verification
ram54288 0:dbad57390bd1 546
ram54288 0:dbad57390bd1 547 You can build your mbed-client port immediately:
ram54288 0:dbad57390bd1 548
ram54288 0:dbad57390bd1 549 ```
ram54288 0:dbad57390bd1 550 # use the target we previously made locally available (not necessary if your target has been published):
ram54288 0:dbad57390bd1 551 yotta link-target <yourtargetname>
ram54288 0:dbad57390bd1 552 # build!
ram54288 0:dbad57390bd1 553 yotta build
ram54288 0:dbad57390bd1 554 ```
ram54288 0:dbad57390bd1 555
ram54288 0:dbad57390bd1 556 A `helloworld-mbedclient` program will be produced inside the `build/<yourtargetname>/test/` directory. This test application may require some changes to compile and run for your platform. Check for compilation errors. If you find any, fix the test application for your testing.
ram54288 0:dbad57390bd1 557
ram54288 0:dbad57390bd1 558 Follow the `readme` [instructions](https://github.com/ARMmbed/mbed-client-linux-example) of the `mbed-client-linux` example to see what the test application can do.