A simple interface to mbed Device Connector, where you just declare variables to push them to the cloud.

Dependents:   Wifi_Get_Test_V1 simple-mbed-client-example simple-client-app-shield simple-sensor-client

Fork of simple-mbed-client by Jan Jongboom

TL;DR? See simple-mbed-client-example to get started immediately.

This library is a simpler interface to mbed Client, making it trivial to expose sensors, actuators and other variables to the cloud. It does not require you to change how you write your code. You can take any local variable, swap it out for a call to Simple Mbed Client, and the variable will automatically be synchronised with mbed Cloud.

For example, here's how you expose the value of a light sensor to the cloud:

SimpleMbedClient client;

SimpleResourceInt light_value = client.define_resource("light/0/value", 0);     // create the var

AnalogIn light(A1);

void read_light_sensor() {
    // light_value behaves just like a normal variable that you can read and write to!
    light_value = light.read_u16();
}

// update every second
Ticker t;
t.attach(&read_light_sensor, 1.0f);

Setting up

First import this library to your project. As Simple Mbed Client also needs a way to talk to the outside world, you'll need a NetworkInterface-object. The easiest way is by using the easy-connect library, so add that to your project as well. See the easy-connect docs on how to specify the connectivity method.

We also need a way of authenticating with mbed Cloud. For this we need a security certificate. Go to mbed Cloud, and select 'GET MY DEVICE SECURITY CREDENTIALS'. Save the certificate as security.h in your project folder.

Now we can initiate Simple Mbed Client and connect it to the internet.

#include "mbed.h"
#include "security.h"
#include "easy-connect.h"
#include "simple-mbed-client.h"

SimpleMbedClient client;

DigitalOut led(LED1, 0);

void registered() {
    led = 1;
}

int main() {
    NetworkInterface* network = connect_to_network(); // if connection failed, network will be NULL
    client.setup(network); // returns a bool, check if it's true

    client.on_registered(&registered);

    while (1) {
        wait_ms(25000);
        client.keep_alive();
    }
}

Defining variables

You can define a new variable by a call to client.define_resource. This function takes five arguments:

  1. path - The URL on which your variable is exposed in mbed Cloud. Needs to be three (3) segments, split by a slash (/) in the form of 'sensor/0/value'. The second segment always needs to be numeric.
  2. defaultValue - The default value of the variable. Needs to be either a string or an integer. Depending on the type that you pass in here the type of the variable is defined.
  3. operation - Some variables might be read-only or write-only (seen from the cloud). Use the operation to define these constraints. It's of type M2MBase::Operation. Default is GET_PUT_ALLOWED.
  4. observable - If set to false, cloud applications cannot subscribe to updates on this variable. Default is true.
  5. callback - Function pointer which is called whenever the value of the variable is changed from the cloud.

The type returned by the function is either SimpleResourceInt or SimpleResourceString. You can assign and read from these variables like any normal local variable.

void name_updated(string new_value) {
    printf("Value is now %s\n", new_value.c_str());
}

SimpleResourceString name = client.define_resource("device/0/name", "jan", M2MBase::GET_PUT_ALLOWED, true, &name_updated);

// we can read and write to this variable, e.g.:
stringstream ss;
ss << name;

// or
name = "pietje";

// are all valid

Defining functions

You can define functions, which do not have a value, but can just be invoked from the cloud, by a call to client.define_function. This function takes two arguments:

  1. path - The URL on which your variable is exposed in mbed Cloud. Needs to be three (3) segments, split by a slash (/) in the form of 'sensor/0/value'. The second segment always needs to be numeric.
  2. callback - Function pointer which is invoked when the function is called. Takes in a pointer, which contains the data being passed in from the cloud.

void play(void* data) {
    if (data) { // data can be NULL!
        // cast it to something useful
    }
}

client.define_function("music/0/play", &play);

Accessing the underlying M2MResource

If you need access to the underlying M2MResource you can do so by calling get_resource on a variable, or by calling client.get_resource if it's a function.

SimpleResourceInt led = client.define_resource("led/0/value", true);

client.define_function("led/0/toggle", &toggleLed);

// now to get the resource
M2MResource* ledResource = led.get_resource();
M2MResource* toggleResource = client.get_resource("led/0/toggle");

Printing variables

Unfortunately printf is kind of dumb, and does not automatically cast the variables. If you want to print any of the Simple Mbed Client variables you'll need to cast yourself.

SimpleResourceInt led = client.define_resource("led/0/value", true);

printf("Value is currently %d\n", static_cast<int>(led));

Event Queue

Simple Mbed Client uses an mbed-events EventQueue - running on a separate RTOS thread - to handle incoming events without blocking the main loop. Both the thread and event queue are created when initializing the library. You can override this behavior by providing your own event queue. In this case no thread is created.

EventQueue myQueue;
SimpleMbedClient client(&myQueue);

You can also use the queue to process your own events, which is very useful when dealing with ISRs. The queue is accessible through the eventQueue() function on the client object and returns a pointer to the queue.

SimpleMbedClient client;

InterruptIn btn(D2);

int main() {
  btn.fall(client.eventQueue()->event(&fall));
}

Changes

RevisionDateWhoCommit message
23:c89df15e88d2 2017-03-21 Jan Jongboom Update mbed-client, works with mbed OS 5.4.1 default tip
22:17b4681e3353 2017-02-08 Jan Jongboom Add SimpleResourceFloat
21:816251388f55 2017-02-08 Jan Jongboom -Wreorder in SimpleResourceInt initialization
20:bfa6cc52d6d7 2017-02-07 Jan Jongboom Data member initializer is not allowed in ARMCC
19:cf570422d4dd 2017-02-07 Jan Jongboom Allow Event's to be passed into define_function, so you can dispatch mDC functions straight on an event loop, rather than manual deferring
18:7b2882874f87 2017-02-07 Jan Jongboom Add EventQueue, auto-update registration and make set() calls safe in ISR
17:200624714d15 2017-02-07 Jan Jongboom Move mbedtls_mbed_client_config.h into simple-mbed-client, allow overriding of constructor and add ServerAddress macro to simple-mbed-client
16:cb980bd39e32 2017-02-06 Jan Jongboom Get rid of stringstream. Save 130K flash and 4K of RAM
15:b7360c7e0f7f 2017-02-06 Jan Jongboom Remove the keep_alive ticker from SimpleClient. Add Callback<void()> overloads for on_registered and on_unregistered.
14:680c2a46cc8a 2016-12-02 Jan Jongboom Switch to TCP as default socket mode
13:a98cabe88e0f 2016-12-02 Jan Jongboom Update to mbed OS 5.2.3
12:26810c6b58e1 2016-09-28 Jan Jongboom Move away from FunctionPointer in favor of Callback
11:4da431479ce3 2016-08-24 Jan Jongboom Don't log when creating route
10:3fecd642d506 2016-08-24 janjongboom Make it compile in ARMCC
9:cfd5d2a7d77d 2016-08-15 Jan Jongboom Ambigious function declaration
8:2c48606ae4ae 2016-08-15 Jan Jongboom do not include IPv4, IPv6 in mbed_lib.json, connectivity lib should handle this
7:8a05fbad93d1 2016-07-21 Jan Jongboom SimpleMbedClient no known conversion on int, need to not set default value on onUpdate call
6:a1a766d45957 2016-07-01 Jan Jongboom Add a way of accessing underlying M2MResource
5:b875aa494b9f 2016-07-01 Jan Jongboom Add CLIENT dependency in simple-client library
4:0f9eae5739dd 2016-06-30 Jan Jongboom Update to latest mbed-os and fix setting empty values
3:ce2322965a27 2016-05-24 Jan Jongboom Move from mbed.bld to mbed-os.lib, and implement updates
2:0a015df677a4 2016-05-17 janjongboom Fix getting variables, and add keep_alive function.
1:75015f627e89 2016-05-15 janjongboom Add some overloads for update callbacks
0:9fa3f3028773 2016-05-15 janjongboom Port of mbed-client-ethernet-c-style to mbed Classic