Austin Blackstone / Mbed 2 deprecated mbed-client-classic-example-lwip

mbed client on ethernet with LWIP

Dependencies:   mbed Socket lwip-eth lwip-sys lwip

Fork of mbed-client-classic-example-lwip by sandbox

mbed-client/docs/porting-guide.md@11:cada08fc8a70, 2016-06-09 (annotated)

Committer:
mbedAustin
Date:
Thu Jun 09 17:08:36 2016 +0000
Revision:
11:cada08fc8a70
Commit for public Consumption

Who changed what in which revision?

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