C++ implementation of ubsub's UDP protocol for secure and reliable bidirectional communication for embedded devices.
The latest version of this library will be kept up-to-date on particle.io
It can be found on the web IDE, or via the CLI
particle library search ubsub
This library is also published to platformio here.
You can use it by typing:
platformio lib install ubsub
Head over to the release tab, download the zip
file, and include it in your project. With Arduino, you're able to do this via their IDE,
and on other projects, you can simply add all the files in src/
to your project.
#include <iostream>
#include <unistd.h>
#include "ubsub.h"
Ubsub client("MyUserId", "MyUserSecret");
void myMethod(const char* arg) {
std::cout << "RECEIVED: " << arg << std::endl;
}
int main() {
std::cout << "Hi there" << std::endl;
if (!client.connect()) {
std::cout << "Failed to connect before timeout" << std::endl;
}
client.listenToTopic("testy", myMethod);
client.publishEvent("Byg2kKB3SZ", "HJ3ytS3SW", "Hi there");
while(true) {
client.processEvents(); // Need to call this to process incoming events and managed items
usleep(5 * 1000);
}
return 0;
}
#include "ubsub.h"
Ubsub client("MyUserId", "MyUserSecret");
float myGlobalVal = 0.0f;
void myMethod(const char* arg) {
// Called method with argument
}
void setup() {
while (!client.connect()) {
// Attempting connect
}
// Listen and publish data
client.listenToTopic("testy", myMethod);
client.publishEvent("Byg2kKB3SZ", "HJ3ytS3SW", "Hi there");
// Automatically watch value and send update when it changes
client.watchVariable("myval", &myGlobalVal);
}
void loop() {
// Do whatever else you need to do
// Need to call this to process incoming events and managed items
client.processEvents();
}
Create an instance of the Ubsub client with the given device info.
Device id/key can either be user id/key OR token id/key.
Support: Arduino, Particle
Enables/disables the client auto-syncing time on devices.
Returns: true
on success
Attempts to establish a connection to ubsub.io. Will wait for WiFi first, sync time if asked to, and negotiate NAT routing.
Must be called prior to any other functions.
Publish an event to Ubsub.io topic.
Listen to a topic on ubsub.io
Callback: void callbackfunc(const char* arg)
Same as listenToTopic, except will create the topic if not exist
Call a topic, by name, with an optional argument.
If the arg is JSON, it will be interpreted as such, otherwise
it will be wrapped like so: {"payload": <arg>}
Watches a variable for changes (char array, int, or float).
If variable change is detected, automatically publishes event to name
.
Receives, pings, and retries any outstanding events. Must be called frequently, such as in your void loop(){}
function.
Gets the last error code that has occurred in the client. 0
is no-error.
Errors: (from ubsub.h)
#define UBSUB_ERR_INVALID_PACKET -1
#define UBSUB_ERR_BAD_VERSION -2
#define UBSUB_ERR_USER_MISMATCH -3
#define UBSUB_ERR_BAD_SIGNATURE -4
#define UBSUB_ERR_TIMEOUT -5
#define UBSUB_ERR_EXCEEDS_MTU -6
#define UBSUB_ERR_SOCKET -7
#define UBSUB_ERR_SOCKET_BIND -8
#define UBSUB_ERR_NETWORK -9
#define UBSUB_ERR_SEND -10
#define UBSUB_ERR_BAD_REQUEST -11
#define UBSUB_ERR_NONCE_DUPE -12
#define UBSUB_MISSING_ARGS -50
#define UBSUB_ERR_UNKNOWN -1000
#define UBSUB_ERR_MALLOC -2000
As part of the distribution, you can also include minijson.h
, which includes a very
primitive and memory-efficient way to build simple JSON. This is useful when you want
to publish multiple pieces of data in a single publish event.
#include "minijson.h"
MiniJsonBuilder builder(128); // 128 is buffer size
builder.open().write("key", "val").write("key2", 23).write("key3", true).close();
client.publishEvent("my-topic", builder.c_str());
- Unix/Linux
- Arduino
- Particle
- ESP8266 Boards
To enable logging, simply define UBSUB_LOG
during build-time. For debug logging,
define UBSUB_LOG_DEBUG
.
Sha256 implementation is from Cathedrow/Cryptosuite with small modifications for compatibility.
Salsa Implementation from: https://github.com/alexwebr/salsa20
See: LICENSE.txt