This post is a bit lengthy. If you prefer, signup to get the full PDF here. ?

After Particle's Mesh deprecation announcement, many have been left to figure out how to deploy their low power sensor networks. There was always the option of using Particle's Built in Bluetooth stack but as it stands today it's not secure.

Previously I had helped form a very simple nRF SDK-based hub and spoke IoT deployment. Unfortunately, it was closed source and the company is no longer around.

So what's a guy to do?

Build another one and make it open. (BSD licensed to be exact!) Open and free for anyone to use adopt and improve upon. Plus if you're building a product that's using the code, you don't have to share your improvements or proprietary code with anyone.

In this post I'll be talking about how to get started with Pyrinas. It uses Nordic's time tested SDK as a basis for the kernel of the system. The main concept of Pyrinas is to abstract as much IoT cruft away so you can focus on your application.

So without further ado, let's chat about what Pyrinas is and what it isn't.

What Pyrinas is

• Is an embedded "kernel", written in C. It's open and permissive IoT development environment you can use for anything you want. Seriously. It's BSD licensed and can be used in closed source applications.
• Using the power of Bluetooth 5.0 Long Range, Pyrinas allows you to communicate with many peripheral devices at one time. Currently Pyrinas has been tested with 3 simultaneous peripheral connections. Theoretically, it can support up to 20 simultaneous connections. (Thanks to Nordic's S140 Softdevice)

• Pyrinas transports its data in two ways

  • In a familiar string format used by Particle
  • A custom Protocol Buffer for raw data transmission.

  That way you have a choice of how you want to process and publish your data!

What Pyrinas isn't

• Pyrinas is not a RTOS (real time operating system). If you have a need to run multiple threaded applications on embedded, Pyrinas is not for you.
• Pyrinas, at this time, does not support Mesh.
• An OS for every single kind of Bluetooth SoC on the market. Due to the tight coupling with Nordic's nRF SDK, Pyrinas only works with Nordic's SoCs.
• A turnkey solution for IoT. Pyrinas is early on it it's development process. The aim is for it to become a viable option for anyone to develop and publish IoT applications the way they want to. There's no vendor lock in. There's no surprises.

Things you'll need

There are a few things you'll need in order to get going with Pyrinas.

• At least 2 Particle Xenons
• At least 1 nRF Development board or J-link programmer
• Associated USB cables

Getting started with an example

Getting started with Pyrinas involves two repositories.

• The OS respository
• The template

The OS directory has all the source, SDK dependencies and toolchain you need to use Pyrinas.

The template is where you add all your application code. The template provides a starting point for you and your project.

Here's how everything goes together:

Clone the OS directory to some place on your machine:

git clone https://github.com/pyrinas-iot/pyrinas-os.git --recurse-submodules

Once complete, change directories to pyrinas-os and run make setup

cd pyrinas-os
make setup

This will download your toolchain and SDK dependencies.

In order to use OTA DFU, you will need to also generate the DFU key for the process:

make gen_key

The files generated by this process will be used later.

Next, we'll want to use the template to make two new projects. In this example we'll have one "hub" and one "sensor." Simply navigate to the template repository and click the Use this template button.

Then name your new repository. Click the Create repository from template button when you're happy with everything.

Then clone your repository to the same directory as pyrinas-os. Make sure you replace <your username> and <repo name> with your own.

cd ..
git clone https://github.com/<your username>/<repo name>.git hub

After this is done, go back and create a new repository from the template. We'll be using this one for the sensor node.

Clone this repository once you're done setting it up in the same place as your hub and pyrinas-os repositories.

Now that we have all our repositories, let's start with our sensor node.

Setting up the sensor node repository

Open up the sensor repository using a program like Microsoft's VS Code. If you have the command line shortcuts you can use code to open it from the terminal:

code sensor

Before we do anything we'll need to set up the symbolic link to pyrinas-os. Make sure you're in the sensor directory and then run ln -s ../pyrinas-os/ using the terminal.

cd sensor
ln -s ../pyrinas-os/ .

This allows your project to use all the code, SDK and toolchains within the pyrinas-os repository! As an added bonus you can do this as many times as you want. Have multiple Pyrinas projects? No problem.

Alright! Now, let's check out the Makefile. You'll want to customize some of the definitions within the file:

# Start: Your configuration!

# Set this to the directory of pyrinas-os
# If you used a symbolic link this points to
# the `pyrinas-os` folder in this repository
OS_DIR := pyrinas-os

# This should be the serial number of your Jlink programmer.
# To find simply run `jlinkexe`
PROG_SERIAL=1234678

# This is your debugger port for Jlink's RTT. If you
# have mulitple, you will have to change this on each app
# your're using
PROG_PORT=19021

# This is where you set your board type. Here are the supported boards:
# xenon - Particle Xenon
BOARD=xenon

# This is where you can name your app something. Make it specific
APP_FILENAME=pyrinas-template

# This determines whether or not you're using debug mode
# Comment this out or change to false
DEBUG=true

# End: Your Configuration

For example, you may want to setup your programmer serial. This allows you to use multiple programmers at the same time. (Very helpful in debugging both devices at the same time) To get your programmer's serial plug in your development board and run jlinkexe.

jlinkexe SEGGER J-Link Commander V6.62a (Compiled Jan 31 2020 12:59:22) DLL version V6.62a, compiled Jan 31 2020 12:59:05

Connecting to J-Link via USB...O.K. Firmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Jan 21 2020 17:30:48 Hardware version: V1.00 S/N: 581758669 License(s): RDI, FlashBP, FlashDL, JFlash, GDB VTref=3.300V

Type "connect" to establish a target connection, '?' for help J-Link>

Find the S/N area. This is your serial number!

Alternatively you can look at the sticker on your development kit. It will contain the serial number for your device.

For the PROG_PORT you want to use different ports for each device you're simultaneously debugging. I've found 19021 and 19020 are perfectly good options for most two-device debugging sessions.

The Makefile also includes the ability to choose a board. In our case there's only one option: xenon. Future revisions of Pyrinas will have multiple options.

APP_FILENAME is the name of your app. We'll rename ours to pyrinas-sensor

Finally, DEBUG is used to halt execution either on an error or restart. For production this should be commented out or set to false. We can leave it as is for now.

The Makefile is also the source for some of the most important commands you'll need during development:

• make build - builds your app.
• make clean - cleans all remnants of your app.
• make debug - opens up the jlinkexe debugger console.
• make erase - erases the chip attached to your programmer.
• make flash - flashes the current app to your connected device.
• make flash_softdevice - flashes the soft_device
• make rtt - opens up the debug console.
• make ota - generates a zip file used for BLE DFU

Basic sensor node code

Now that we have some of the basics out of the way, let's create a very simple application that publishes on a set interval. If you look at app.c, you'll see some code in the setup() function. Let's delete all the commented out code. (We'll use it later for the hub though)

Your code should now look something like:

#include "app.h"

void setup()
{
  BLE_STACK_PERIPH_DEF(init);

  // Configuration for ble stack
  ble_stack_init(&init);

  // Start advertising
  advertising_start();
}

void loop()
{
}

Now let's create a timer that we'll use to publish on a set interval. Under #include "app.h" create a new timer:

#include "app.h"

timer_define(m_sensor_timer);

We also need to set it up in the setup() function:

// Sensor timer
timer_create(&m_sensor_timer, TIMER_REPEATED, sensor_timer_evt);

You'll notice that timer_create is referring to a event callback called sensor_timer_evt. We'll need to create that guy as well:

static void sensor_timer_evt() {
    // We'll come back in a sec
}

The last thing is to start the timer. Let's do that underneath timer_create:

// Start
timer_start(&m_sensor_timer, 1000);

This will start our repeating timer on a 1 second interval. (timer_start is configured using milliseconds)

Now, inside sensor_timer_evt we'll publish some data. First though we need to make sure that Bluetooth is connected using ble_is_connected.

static void sensor_timer_evt
{
  // Check if we're connected
  if (ble_is_connected())
  {
    // Sends "ping" with the event name of "data"
    ble_publish("data", "ping");
  }
}

Inside the if statement, we'll use ble_publish. The first argument is the name of the event and the second is the value.

Next, in order to receive messages from the other end we'll need to setup a callback:

// Configuration for ble stack
ble_stack_init(&init);

// Setup BLE callback
ble_subscribe("data", ble_evt);

We'll define ble_evt at the top of the file:

static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);
}

In this case we'll use NRF_LOG_INFO to print out the message from the hub.

Finally, in order to get the MAC address easily, we'll have to add a call to print it out in setup().

// Print the address
util_print_device_address();

In the end your file should look something like this:

#include "app.h"

timer_define(m_sensor_timer);

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);
}

static void sensor_timer_evt()
{
  // Check if we're connected
  if (ble_is_connected())
  {
    // Sends "ping" with the event name of "data"
    ble_publish("data", "ping");
  }
}

void setup()
{
  BLE_STACK_PERIPH_DEF(init);

  // Configuration for ble stack
  ble_stack_init(&init);

  // Setup BLE callback
  ble_subscribe("data", ble_evt);

  // Start advertising
  advertising_start();

  // Sensor sensor timer.
  timer_create(&m_sensor_timer, TIMER_REPEATED, sensor_timer_evt);

  // Start
  timer_start(&m_sensor_timer, 1000);

  // Print the address
  util_print_device_address();
}

void loop()
{
}

Next, we'll program it to some hardware!

Flashing the basic sensor code:

For this step you'll need to have a Xenon handy. You'll also need a programmer, programming cable and two Micro-B USB cables. Here's a picture of everything connected:

Once connected and powered run these commands:

make erase
make flash_softdevice
make flash
make debug

Then in a separate terminal window run

make rtt

make debug and make rtt will create a debugging session. You can issue commands in the make debug terminal to control the device as well. For instance, r followed by Enter will restart the device. (By far my most common use case).

If you've flashed everything successfully, your device should start blinking green. That's a good sign!

Additionally, if you take a look at the make rtt side your output should be similar to this:

###RTT Client: Connecting to J-Link RTT Server via localhost:19021 ...

###RTT Client: Connected.

SEGGER J-Link V6.62a - Real time terminal output J-Link OB-SAM3U128-V2-NordicSemi compiled Jan 21 2020 17:30:48 V1.0, SN=581758669 Process: JLinkExe app_timer: RTC: initialized. app: Boot count: 4 app: Pyrinas started. app: Address: 11:22:33:44:55:66

Take note of the address displayed above. We'll need that for the hub code!

Setting up the hub repository

If you haven't already, clone your hub repository locally. We'll want to do some of the same steps as we did with the sensor repo like:

• Setting up the symbolic link
• Updating the Makefile
  • Setting your PROG_SERIAL
  • Setting PROG_PORT to a port not used by the sensor setup. 19020 in this case is fine.
  • Setting APP_FILENAME to pyrinas-hub

If you need a reminder how any of these steps work, go back and review the earlier section.

Next, we'll want to open app.c and uncomment the central/hub based code. Plus you'll want to remove the default un-commented code. Your setup() should look something like this:

void setup()
{
  // Default config for central mode
  BLE_STACK_CENTRAL_DEF(init);

  // Add an addresses to scan for
  ble_gap_addr_t first = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x81, 0x64, 0x4C, 0xAD, 0x7D, 0xC0}};
  init.config.devices[0] = first;

  ble_gap_addr_t second = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x7c, 0x84, 0x9d, 0x32, 0x8d, 0xe4}};
  init.config.devices[1] = second;

  // Increment the device_count
  init.config.device_count = 2;

  // Configuration for ble stack
  ble_stack_init(&init);

  // Start scanning.
  scan_start();
}

You'll notice immediately that there are two clients/devices defined here. Let's remove the second one. Should you, in the future, want to connect more devices this is an example of how to do it.

Reminder: also make sure that you change the init.config.device_count to 1.

Then, you'll want to update the .addr field in ble_gap_addr_t first to match the address we got earlier from make rtt:

// Add an addresses to scan for
ble_gap_addr_t first = {
    .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
    .addr = {0x11,0x22,0x33,0x44,0x55,0x66}};
init.config.devices[0] = first;

The address field uses raw bytes, so it has to be represented that way. Remove the : and place 0x in front of each byte. We end up going from 11:22:33:44:55:66 to {0x11,0x22,0x33,0x44,0x55,0x66}

Now before we flash anything, let's also set up the Bluetooth event handler. As with earlier we'll use ble_subscribe to attach an event handler:

// Setup BLE callback
ble_subscribe("data", ble_evt);

Then place the function at the top of the file:

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);

  ble_publish("data", "pong");
}

You'll notice we're printing out the message using NRF_LOG_INFO. We're also sending a message back to the sensor in the form of ble_publish("data","pong"); In other-words we're playing a game of ping-pong between the two devices!

In the end your code should look something like this:

#include "app.h"

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);

  ble_publish("data", "pong");
}

void setup()
{
  // Default config for central mode
  BLE_STACK_CENTRAL_DEF(init);

  // Add an addresses to scan for
  ble_gap_addr_t first = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x11, 0x22, 0x33, 0x44, 0x55, 0x66}};
  init.config.devices[0] = first;

  // Increment the device_count
  init.config.device_count = 1;

  // Configuration for ble stack
  ble_stack_init(&init);

  // Setup BLE callback
  ble_subscribe("data", ble_evt);

  // Start scanning.
  scan_start();
}

void loop()
{
}

Reminder: make sure you set ble_gap_addr_t first or the two devices will not connect!

To program, connect the Xenon to program as you did before. We'll flash it using the same methods as before:

make erase
make flash_softdevice
make flash
make debug

Then in a separate terminal window run

make rtt

Then take a look at each of the make rtt screens. There should be some output! For the hub it should look something like this:

Process: JLinkExe app: Boot count: 4 app: Pyrinas started. ble_m_central: Connected to handle 0x0 ble_m_central: Protobuf Service discovered app: data: ping app: data: ping

And the sensor side like this:

Process: JLinkExe app_timer: RTC: initialized. app: Boot count: 4 app: Pyrinas started. app: Address: 11:22:33:44:55:66 ble_m_periph: Notifications enabled! app: data: pong app: data: pong

The ping and pong messages should continue until you stop them. Awesome! If you get any warnings like this one:

Unable to write. Notifications not enabled!

Use the reset button on either of the devices. This should fix the problem.

Side note: the pairing process for Bluetooth is inherently insecure. Once the pairing process is complete though, the devices are secure. (With the caveat that no one was sniffing the pairing process!) There may be improvements on security in the future.

Congrats! ?If you've made it this far, you've deployed your first Pyrinas hub and sensor client!

For more information about what Pyrinas can do you should check out the header files under pyrinas-os/include/. Also, Pyrinas can do anything that you'd normally be able to do with Nordic's SDK. Nordic's Infocenter is a great resource for learning more about what the SDK has to offer.

What does the future hold for Pyrinas?

All future tasks for Pyrinas are shared openly on the Github Repo. Here are some of the high level improvements on the roadmap:

• Particle Boron + LTE support - That's right! Cellular will be coming to Pyrinas. As of this writing, the first board to support Pyrinas LTE will be Particle's Boron.
• MQTT (over TLS) and HTTPS support - Once we have cellular, we need something to communicate with. That's where MQTT and HTTPS come in. They're some of the most popular protocols for IoT today.
• Built in remote OTA support - As it stands today, devices programmed with Pyrinas uses Nordic's Secure Bootloader. That means they can be updated over the air by a computer or cellphone nearby. This isn't sustainable for long term deployments though! Instead, you will be able to push updates to Pyrinas devices over the Cloud. Yup. No reason to get off your couch, you can deploy your updates from anywhere.
• Dynamic configuration and management - adding and removing devices from a Pyrinas system currently takes some effort. In future revisions, it will be easier to add and remove devices on the fly. This allows for remote device management with zero headaches.
• Support for pre-certified modules and other development boards based on Nordic's nRF52840. Currently the Xenon is the only supported board. Development boards aren't great for full production though. Stay tuned for support for pre-certified modules from vendors like Fanstel and more..
• Support for more development environments. Currently Pyrinas supports Mac only.

Star and Watch!

This is only the tip of the iceberg! Stay tuned for more updates and make you you star and watch the repository.

Or, better yet, looking to help out? Contributions are welcome!

You can read other articles on my blog, jaredwolff.com

If you're developing any type of IoT product, inevitably you'll need some type of mobile app. While there are easy ways, they're not for production use.

In this tutorial, we'll talk about the basics of Particle app development. You'll learn about some of the many app frameworks you can take advantage of. Plus there's libraries, tricks, and tools along the way to make your life a lot easier.

App Frameworks

Sometimes it's dang near irritating to program multiple applications natively. You see, Swift (or Objective C ?) and Java aren't terrible at first glance (well, maybe except for Obj-C ?). But when you're resource constrained, you have to figure out a new game plan. That's where App Frameworks come in.

These frameworks allow an app developer to write, build and test cross platform apps. In some cases, the frameworks convert your app into native code. That means that they run as fast and as well as one written in Swift or Java.

I did the research and as of January 2020, here are some of the most supported frameworks:

• Framework7
• Flutter
• NativeScript
• ReactNative
• Ionic
• Cordova / PhoneGap
• Meteor
• Xamarin

The list goes on for days.

I've used a few of these frameworks in the past. I've built a Meteor app which (surprisingly) worked. In the end I had to pick one though. What did I go with?

NativeScript.

For the most part, NativeScript's documentation and on-boarding experience is fantastic. Not only can you preview your app inside an emulator but you can load it directly to your phone too!

One of the cool things about NativeScript is that it supports TypeScript. TypeScript is a superset of JavaScript with some extra wiz-bang features.

Unlike other languages, JavaScript technically has no types. If you've done any Particle development you likely know what a type is. We're talking about int, String, float and more. i.e. they're directives to to make sure your JavaScript code stays consistent.

NativeScript is also compatible with most major JavaScript web frameworks. This includes Vue.Js and Angular.

I've only noticed one major drawback thus far: the mobile preview mode (tns preview command) does not pay well with native libraries. If you have some native platform specific libraries, you'll have to use the emulator or a device (if you have one).

If you're gung-ho and you want to build multiple apps in their respective languages, the more power to you. There is an advantage over the above frameworks: tried and true Particle SDKs.

Available Libraries & SDKs

Particle has gone out of their way to make app development a little easier. This is thanks to the massive development work that has gone into their own SDKs. Yup, gone are the days you have to write manual HTTP request handlers.

Here's a link to both the iOS and Android SDKs:

• iOS
• Android

Though we won't be covering them here, they reflect all the potential calls that you can make using the Cloud API.

Speaking of Cloud API, Particle has also developed a Node.js library as well. As you can imagine, you can use this for your server side code or JavaScript based app frameworks. Sadly, it doesn't work with NativeScript. Frameworks that use a WebView should be more compatible.

In the case of this tutorial, we'll be mostly focusing on the Cloud API. This way you have a good understanding of the overall system. It may seem intimidating but if you do it right, you'll get the hang of it real fast.

Making API Calls

In NativeScript you can't use libraries like [request](https://github.com/request/request). (Which happens to be the library Particle's very own DMC used in the CLI — DMC if you're reading this, Hi!) You'll have to use the provided HTTP module.

If you scroll all the way to the bottom of that page, you'll see a fully fledged POST example. I'll reproduce it here but with some Particle specific changes:

// Create form post data
var data = new FormData();
data.append("name", "update");
data.append("data", "It's hammer time!");
data.append("private", "true");
data.append("access_token", _token);

// Configure the httpModule
return httpModule
    .request({
        url: `https://api.particle.io/v1/devices/events`,
        method: "POST",
        content: data
    })
    .then(
        response => {
            const result = response.content.toJSON();
            console.log(result);
        },
        e => {
            if (e) console.log(e);
        }
    );

The above is an example of what's equivalent to Particle.publish in DeviceOS. Let's break down the parts.

First of all, one of the main gotchas of Particle's Web API is the data format. I first expected that they use JSON but I was sorely wrong. After actually reading the documentation I realized that most POST requests were actually application/x-www-form-urlencoded. That means when you submit data, it's the equivalent to hitting the submit button on an HTML form.

Fortunately, there is an easy way to assemble form data in Node/JavaScript. We can use the FormData() object. Take a look at the above. There should be some familiar parameter names in the data.append calls.

"name" refers to the name of the event you're publishing to.

"data" refers to the string formatted data that you're publishing.

"private" dictates whether or not you want to broadcast this data to the whole Particle world, or just your little corner of it.

"access_token" is a token that you can generate in order to make these API calls. Without a token though, you're dead in the water.

Getting a Token

Where do we get this elusive access_token?

At first I had no idea.

I created an OAuth user and secret in the console. That lead to a dead end. Fiddled around with different API calls and settings. Nothing. Then it hit me like a ton of bricks. There's an access_token attached to the curl request on every device page!

Open up any device, click the little console button near Events. A popup with instructions an a URL will pop up. Copy the text after access_token=. That is your access_token! See below:

You can use this token to make calls to the Particle API. This can be to subscribe, publish, write to a function, read variables and more.

Through the command line

That's nice and everything but how the heck can you programmatically generate one? One way is with the command line.

particle token create is the name of the command you need to know about. When you run it, you'll be prompted to login. (Also enter your Authenticator code if you use one.) Then the command line will spit out a shiny new access_token you can use with the API!

Through the API itself

If you couldn't guess, particle token create is a frontend to a raw API call. You can make these API calls directly too. Here's what it looks like in NativeScript.

// Create form post data
var data = new FormData();
data.append("username", "jaredwolff");
data.append("password", "this is not my password");
data.append("grant_type", "password");
data.append("client_name", "user");
data.append("client_secret", "client_secret_here");

// Configure the httpModule
return httpModule
    .request({
        url: `https://api.particle.io/v1/oauth/token`,
        method: "POST",
        content: data
    })
    .then(
        response => {
            const result = response.content.toJSON();
            console.log(result);
        },
        e => {
            if (e) console.log(e);
        }
    );

This call may get more complicated. Mostly in the case if you have two factor authorization setup. It's well worth it when you figure it all out. After all, no one wants to manually create auth tokens if they don't have to!

Now you're ready to write and read from your devices. There's one thing though that may trip you up. Subscribing to events can be troublesome with a regular HTTP client. So much so that if you try to do it with NativeScript's HTTP client, it will lock up and never return. Luckily there is a way to handle these special HTTP calls.

Server Sent What?

Server Sent Events (SSE for short) is an HTTP/S subscription functionality. It allows you to connect to a SSE end point and continuously listen for updates. It's a similar web technology to what companies use for push notifications. It does require some extra functionality under the hood though...

SSE Library

After much head scratching and searching I stumbled upon nativescript-sse. It looked simple enough that I could start using immediately. More problems arose when I tried to use it though.

First, it turns out you can't use the library in tns preview mode. The alternative is to use tns run ios --emulator or use tns run ios with your iPhone connected to your computer. The non-emulator command will automatically deliver your prototype app.

Side note: I had already set up my phone in Xcode. You may have to do this yourself before tns run ios is able to find and deploy to your phone.

Secondly, once I got the library working, I noticed I would get some very nasty errors. The errors seemed to happen whenever a new message from Particle came along.

Turns out the underlying Swift library for iOS had fixed this last year. So I took it upon myself to figure out how to upgrade the NativeScript plugin. I'll save you the time to say that it can be a pain and there is a learning curve!

Fortunately after some hacking I got something working. More instructions on how to compile the plugin are in the README. Alternatively, you can download a pre-built one on the Release page of the repository.

Download the .tgz file to wherever you like. Then, you can add it using tns plugin add. The full command looks like this:

tns plugin add path/to/plugin/file.tgz

You can check to make sure the library is installed by running tns plugin list

**jaredwolff$ tns plugin list
Dependencies:
┌─────────────────────┬──────────────────────────────────────────────────────────────────────────────────┐
│ Plugin              │ Version                                                                          │
│ @nativescript/theme │ ~2.2.1                                                                           │
│ nativescript-sse    │ file:../../Downloads/nativescript-sse/publish/package/nativescript-sse-4.0.3.tgz │
│ tns-core-modules    │ ~6.3.0                                                                           │
└─────────────────────┴──────────────────────────────────────────────────────────────────────────────────┘
Dev Dependencies:
┌──────────────────────────┬─────────┐
│ Plugin                   │ Version │
│ nativescript-dev-webpack │ ~1.4.0  │
│ typescript               │ ~3.5.3  │
└──────────────────────────┴─────────┘
NOTE:
If you want to check the dependencies of installed plugin use npm view <pluginName> grep dependencies
If you want to check the dev dependencies of installed plugin use npm view <pluginName> grep devDependencies**

Once installed, invoking the library takes a few steps. Here's an example:

import { SSE } from "nativescript-sse";

sse = new SSE(
            "https://api.particle.io/v1/events/blob?access_token=<your access token>",
            {}

// Add event listener
sse.addEventListener("blob");

// Add callback
sse.events.on("onMessage", data=>{
    // TODO: do stuff with your event data here!
    console.log(data);
});

// Connect if not already
sse.connect();

First you need to import and create an instance of the library. When you create the instance, you will have to enter the URL that you want to use.

In this case we'll be doing the equivalent of Particle.subscribe(). It should look something similar to the above: https://api.particle.io/v1/events/<your event name>?access_token=<your access token>.

Replace <your event name> and <your access token> with the name of your event and your freshly created token!

Then you set up the library to listen for the event you care about. In this case blob is the event I most care about.

Then make sure you configure a callback! That way you can get access to the data when blob does come along. I've made a TODO note where you can access said data.

Finally, you can connect using the .connect() method. If you don't connect, SSE will not open a session and you'll get no data from Particle.

Placement of the code is up to you but from the examples it looks like within the constructor() of your model is a good place.(https://github.com/jaredwolff/nativescript-sse/blob/master/demo/app/main-view-model.ts)

Other Examples

If you're curious how to use SSE in other places I have another great example: Particle's CLI.

Particle uses the [request](https://github.com/request/request) library to handle SSE events in the app. Whenever you call particle subscribe blob it invokes a getStreamEvent further inside the code. You can check it out here. The request library has more information on streaming here.

More resources

This is but the tip of the iceberg when it comes to connecting with Particle's API. Particle has some great documentation (as always) you can check out. Here are some important links:

• API documentation
• Javascript SDK
• iOS SDK
• Android SDK

Conclusion

In this post we've talked about app frameworks, NativeScript, NativeScript plugins and Server Sent Events. Plus all the Particle related things so you can connect your NativeScript app to Particle's API.

I hope you've found this quick tutorial useful. If you have any questions feel free to leave a comment or send me a message. Also be sure to check out my newly released guide. It has content just like this all about Particle's ecosystem.

Until next time!

This post was originally from https://www.jaredwolff.com/how-to-develop-particle-iot-apps-using-nativescript/

Ever want to add presence or location tracking to a project? Frustrated by the solutions (or lack thereof)?

Do not worry, you're not the only one!

In this post you'll learn how to implement a very basic tracking and notification application. We'll be using a Particle Argon and a Tile Mate.

By the end you'll be able to tell when the Tile is present or not. Plus we'll use Pushover to send push notifications to the devices of your choosing.

Let's get going!

Note before we get started, this post is lengthy. You can download the PDF version so you can save and view it later.

Initial investigation

The idea of using a Tile wasn't obvious at first glance. Ideally, using a phone seemed to make more sense. Unfortunately, this wasn't as a viable option. It would require some more research and the creation of a Bluetooth iOS app.

So, the idea of using a phone was out.

Then I thought, "What devices do advertise all the time?"

That is what led me down the path of a tracker like Tile.

After it arrived there was some customary testing. First stop, the Tile application.

I was able to connect and use the device. I even made it play a catchy tune. ?

Then, I moved on to using one of the Bluetooth scanner apps. I scrolled through all the results and Bingo. There was the Tile!

I even waited a few hours and checked it again. I wanted to make sure it didn't go to sleep after a while. Turns out, it's always advertising. As far as I can tell, about every 8 seconds.

All of this testing lead to one conclusion: it could be easily used for presence detection.

The next step in the process was trying to figure out how to get it working with an Argon.

Advertising

As we had gathered in the previous step, we know that the Tile is advertising about every 8 seconds. That means it should be easily scanned for using any device including an Argon, Zenon or Boron.

For this example I suggest you use an Argon. This is because Bluetooth and Mesh share the same radio. When scanning for the Tile, the Xenon connected to Mesh would often miss the advertising packets. This would lead to false negatives (and frustration!).

Along the same lines, you'll want to make sure your Argon is connected to no mesh network. You can remove it using the CLI. Connect your device to your computer and run the following command:

particle mesh remove <device name/ID>

Make sure that you replace with your device's name or ID.

Alright, back to the good stuff.

Advertising can have a few different purposes in Bluetooth. Typically though, it marks the beginning of the pairing phase. That way other devices know that the advertising device is available.

Additionally, the advertising device will indicate what services it has. We can use this knowledge to filter out devices that don't match.

For example, here's a screenshot of the services available on the Tile device:

When scanning we'll double check that the device we're connecting to has the service UUID of 0xfeed.

Before we get deep into Bluetooth land though, let's set up our app for debugging using the Logger.

Logging

In this tutorial we'll be using the Logger. It allows you to display log messages from your app using particle serial monitor.

One of the cooler features about the logger is the idea of message hierarchy. This allows you, the designer, to selectively mute messages that may not be necessary.

For example, if you have messages used for debugging. You could remove them or comment them out. Or, you could increase the LOG_LEVEL so they're effectively ignored.

Here are the logging levels which are available in logging.h in Particle's device-os repository:

// Log level. Ensure log_level_name() is updated for newly added levels
typedef enum LogLevel {
    LOG_LEVEL_ALL = 1, // Log all messages
    LOG_LEVEL_TRACE = 1,
    LOG_LEVEL_INFO = 30,
    LOG_LEVEL_WARN = 40,
    LOG_LEVEL_ERROR = 50,
    LOG_LEVEL_PANIC = 60,
    LOG_LEVEL_NONE = 70, // Do not log any messages
    // Compatibility levels
    DEFAULT_LEVEL = 0,
    ALL_LEVEL = LOG_LEVEL_ALL,
    TRACE_LEVEL = LOG_LEVEL_TRACE,
    LOG_LEVEL = LOG_LEVEL_TRACE, // Deprecated
    DEBUG_LEVEL = LOG_LEVEL_TRACE, // Deprecated
    INFO_LEVEL = LOG_LEVEL_INFO,
    WARN_LEVEL = LOG_LEVEL_WARN,
    ERROR_LEVEL = LOG_LEVEL_ERROR,
    PANIC_LEVEL = LOG_LEVEL_PANIC,
    NO_LOG_LEVEL = LOG_LEVEL_NONE
} LogLevel;

Cool, log levels. But how do we use them?

We can use them by invoking one of these functions:

Log.trace, Log.info, Log.warn, Log.error.

For example:

Log.trace("This is a TRACE message.");

If we set the log level to LOG_LEVEL_INFO we'll only see messages from Log.info, Log.warn, and Log.error. LOG_LEVEL_WARN? Only Log.warn and Log.error will show up. (Hopefully you get the idea.)

To set it up, we'll set the default level to LOG_LEVEL_ERROR. We'll also set the app specific LOG_LEVEL to LOG_LEVEL_TRACE. The end result should look something like this

// For logging
SerialLogHandler logHandler(115200, LOG_LEVEL_ERROR, {
    { "app", LOG_LEVEL_TRACE }, // enable all app messages
});

This way we don't get spammed with DeviceOS log messages. Plus, we get all the applicable messages from the app itself.

By the way, if you want to set your device to a single LOG_LEVEL you can set it up like this:

SerialLogHandler logHandler(LOG_LEVEL_INFO);

As you continue your journey using Particle's DeviceOS you'll soon realize how handy it can be. Now, let's move on to the good stuff!

Setting it up

First, we'll want to make sure we're using the correct version of DeviceOS. Any version after 1.3 will have Bluetooth. You can get the instructions here.

Next we'll want to start scanning for the Tile. We'll want do do this in the loop() function at a specified interval. We'll use a millis() timer in this case:

// Scan for devices
if( (millis() > lastSeen + TILE_RE_CHECK_MS) ){
    BLE.scan(scanResultCallback, NULL);
}

Make sure you define lastSeen at the top of the file like so:

system_tick_t lastSeen = 0;

We'll use it to track the last time the Tile has been "seen". i.e. when the last time the Argon saw an advertising packet from the Tile.

TILE_RE_CHECK_MS can be defined as

#define TILE_RE_CHECK_MS 7500

This way we're checking, at the very minimum, every 7.5 seconds for advertising packets.

In order to find the Tile device we'll use BLE.scan. When we call it, It will start the scanning process. As devices are found scanResultCallback will fire.

For now, we can define scanResultCallback at the top of the file:

void scanResultCallback(const BleScanResult *scanResult, void *context) {
}

You notice that it includes a BleScanResult. This will contain the address, RSSI and device name (if available) and available service information. This will come in handy later when we're looking for our Tile device!

Remember, that BLE.scan does not return until scanning has been completed. The default timeout for scanning is 5 seconds. You can change that value using BLE.setScanTimeout(). setScanTimeout takes units in 10ms increments. So, for a 500ms timeout would require a value of 50.

For the case of this app, I'd recommend using a value of 8s (8000ms). You can set it like this:

BLE.setScanTimeout(800);

In this case, the device will scan for as long as it takes the Tile to advertise. That way it's less likely to miss an advertising packet.

Handling Scan Results

Now that we have scanResultCallback lets define what's going on inside.

We first want to get the service information inside the advertising data. The best way is to use scanResult->advertisingData.serviceUUID. We'll pass in an array of UUIDs what will be copied for our use.

BleUuid uuids[4];
int uuidsAvail = scanResult->advertisingData.serviceUUID(uuids,sizeof(uuids)/sizeof(BleUuid));

This will populate uuids that way you can iterate over them. uuidsAvail will equal the amount of available UUIDs.

On our case we're looking for a particular UUID. We'll define it a the top of the file:

#define TILE_UUID 0xfeed

Normally UUIDs are much longer. A short UUID like this means it has been reserved or is part of the Bluetooth specification. In either case we'll be checking for it in the same way we would check a 32bit or 128bit version.

For diagnostic reasons we can also print out the device information. In this case the RSSI and the device MAC address is handy:

// Print out mac info
BleAddress addr = scanResult->address;
Log.trace("MAC: %02X:%02X:%02X:%02X:%02X:%02X", addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]);
Log.trace("RSSI: %dBm", scanResult->rssi);

Finally let's set up a loop to see if the device found has the UUID:

// Loop over all available UUIDs
// For tile devices there should only be one
for(int i = 0; i < uuidsAvail; i++){

    // Print out the UUID we're looking for
    if( uuids[i].shorted() == TILE_UUID ) {
        Log.trace("UUID: %x", uuids[i].shorted());

        // Stop scanning
        BLE.stopScanning();

        return;
    }
}

We can easily compare the "shorted" version of the UUID with TILE_UUID. It's a simple integer so no complicated memory compare operations are necessary. So, using if( uuids[i].shorted() == TILE_UUID ) works just fine.

You can also use Log.trace to print out diagnostic information. In this case we're using it to print out the shorted() version of the UUID.

Test It!

Let's test what we have so far!

Program the app to your Argon. Open the terminal and run particle serial monitor to view the debug messages. Heres an example of what you may see:

0000005825 [app] TRACE: MAC: 65:C7:B3:AF:73:5C
0000005827 [app] TRACE: RSSI: -37Bm
0000005954 [app] TRACE: MAC: B3:D9:F1:F0:5D:7E
0000005955 [app] TRACE: RSSI: -62Bm
0000006069 [app] TRACE: MAC: C5:F0:74:3D:13:77
0000006071 [app] TRACE: RSSI: -62Bm
0000006217 [app] TRACE: MAC: 65:C7:B3:AF:73:5C
0000006219 [app] TRACE: RSSI: -39Bm
0000006224 [app] TRACE: MAC: B3:D9:F1:F0:5D:7E
0000006225 [app] TRACE: RSSI: -62Bm
0000006296 [app] TRACE: MAC: D7:E7:FE:0C:A5:C0
0000006298 [app] TRACE: RSSI: -60Bm
0000006299 [app] TRACE: UUID: feed

Notice how the message includes TRACE and also [app]? That means it's a trace message originating from the application code. Handy right?

This code does get spammy quick, especially if you're in an environment with lots of advertising Bluetooth devices. If you're Tile is on and running eventually you'll see a message UUID: feed. That means your Argon found the Tile!

Next we'll use the onboard Mode button to "program" the Tile's address to memory. That way we can filter out all the devices we don't care about.

Add Device On Button Push

First we need to figure out how to monitor the Mode button. The best bet, according to the documentation is to use System.on.

System.on(button_click, eventHandler);

The first argument is the name of the system event. In our case it's button_click. The second argument is an event handler function. We'll call it eventHandler for now.

Now let's create eventHandler

void eventHandler(system_event_t event, int duration, void* )
{

}

Important: you can't use the Log function inside eventHandler. An easy way to test it is to toggle the LED on D7. Let's set it up!

Initialize the LED in setup()

// Set LED pin
pinMode(D7,OUTPUT);

Then we can add this inside eventHandler

if( event == button_click ) {
    if( digitalRead(D7) ) {
        digitalWrite(D7,LOW);
    } else {
        digitalWrite(D7,HIGH);
    }
}

We can then write to D7 (the onboard blue LED). We can even use digitalRead to read what the state of the LED is. It will respond with HIGH or LOW depending on the situation.

Load the firmware onto the device and we'll have nice control over the blue LED!

In the next section, we'll use the Mode button to put the device into a "learning" mode. This will allow us to do a one touch setup with the target Tile device.

Storing Address to EEPROM

In this next step we'll store the address of the Tile into EEPROM. That way when the device is restarted or loses power we'll still be able to identify the Tile later on.

There is one lingering question though. How do we get it to save the address in the first place?

By monitoring the button press, we can put the device into a "learning" mode. The device will scan for a Tile, and save the address if it finds one.

First let's add a conditional within if( uuids[i].shorted() == TILE_UUID ):

// If we're in learning mode. Save to EEPROM
if( isLearningModeOn() ) {
    searchAddress = scanResult->address;
    EEPROM.put(TILE_EEPROM_ADDRESS, searchAddress);
    setLearningModeOff();
}

We'll use the status of D7 as a way of knowing we're in "learning mode". We do this by reading D7 using digitalRead(D7). Let's create a function that makes this more clear:

bool isLearningModeOn() {
    return (digitalRead(D7) == HIGH);
}

We can also replace the digitalWrite(D7,LOW); and digitalWrite(D7,HIGH); with similar functions. That way it's more straight forward what we're doing.

// Set "Learning mode" on
void setLearningModeOn() {
    digitalWrite(D7,HIGH);
}

// Set "Learning mode" off
void setLearningModeOff() {
    digitalWrite(D7,LOW);
}

Then, we assign a global variable searchAddress as the scan result. We setup searchAddress like this at the top of the file:

BleAddress searchAddress;

Next we want to save it to non-volatile memory using EEPROM.put. TILE_EEPROM_ADDRESS is defined as 0xa. You can define TILE_EEPROM_ADDRESS to use whatever memory address tickles your fancy. Here's the full definition placed at the top of the file.

#define TILE_EEPROM_ADDRESS 0xa

Finally, we turn off the LED and "learning mode" using setLearningModeOff()

Every time a device is found we'll use millis() to set lastSeen. Additionally, we can track the last RSSI using lastRSSI. It's a cheap way to to know approximately how close the device is. We'll use scanResult->rssi to get this information and set it to the lastRSSI variable.

Overall, your changes should look something like this:

...

// Print out the UUID we're looking for
if( uuids[i].shorted() == TILE_UUID ) {
    Log.trace("UUID: %x", uuids[i].shorted());

    // If we're in learning mode. Save to EEprom
    if( isLearningModeOn() ) {
        searchAddress = scanResult->address;
        EEPROM.put(TILE_EEPROM_ADDRESS, searchAddress);
        setLearningModeOff();
    }

    // Save info
    lastSeen = millis();
    lastRSSI = scanResult->rssi;

    // Stop scanning
    BLE.stopScanning();

    return;
}

Before this function, we can filter out devices that don't match our searchAddress. Add the following before if( uuids[i].shorted() == TILE_UUID ):

// If device address doesn't match or we're not in "learning mode"
if( !(searchAddress == scanResult->address) && !isLearningModeOn() ) {
    return;
}

This will skip over devices that don't match. It will only proceed if the address matches or we're in "learning mode".

Now, in order for us to load searchAddress on startup, we'll have to load it from flash. Add this line to your setup():

EEPROM.get(TILE_EEPROM_ADDRESS, searchAddress);

Then, check to make sure the address is valid. It won't be valid if all the bytes are 0xFF:

// Warning about address
if( searchAddress == BleAddress("ff:ff:ff:ff:ff:ff") ) {
    Log.warn("Place this board into learning mode");
    Log.warn("and keep your Tile near by.");
}

We should be able to "teach" our Argon the address of our Tile. Let's test it out!

Test it.

Now if we compile and run the app, notice how there's no more log output? We have to "teach" the Tile address to the Particle Device. So, hit the mode button. The blue LED should turn on.

Once your Tile has been found the LED will turn off and you'll see some output on the command line. Similar to what we've seen before:

0000006296 [app] TRACE: MAC: D7:E7:FE:0C:A5:C0
0000006298 [app] TRACE: RSSI: -60Bm
0000006299 [app] TRACE: UUID: feed

The device has been committed to memory!

You can also check if it's still saved after a reset. Hit the reset button and check for the same output as above. If it's showing up, we're still good!

Update the Cloud

Finally let's set up a function called checkTileStateChanged. We'll use it to check for changes to the state of the Tile on a regular interval.

bool checkTileStateChanged( TilePresenceType *presence ) {

}

The main purpose of this function is to compare the lastSeen variable with the "timeout" duration. In our case, our timeout duration is TILE_NOT_HERE_MS which should be set to

#define TILE_NOT_HERE_MS 30000

near the top of your program. There's also two more conditions to look for. One where lastSeen is equal to 0. This is usually because the app hasn't found the Tile yet after startup.

The last case would be if the device has been seen and lastSeen is not 0. So within checkTileStateChanged let's put everything together.

// Check to see if it's here.
if( millis() > lastSeen+TILE_NOT_HERE_MS ) {

} else if ( lastSeen == 0 ) {

} else {

}

return false;

Now we only want this function to return true if the state has changed. So we'll need to take advantage of the TilePresenceType pointer in the agreement.

TilePresenceType is simply an enumeration of all the possible states. You can stick it at the top of your file as well. Here it is:

typedef enum {
    PresenceUnknown,
    Here,
    NotHere
} TilePresenceType;

You'll also need a global variable that we can pass to the function. Set this at the top of your file as well:

// Default status
TilePresenceType present = PresenceUnknown;

Now, we can compare at each stage. Does it meet the criteria? Is the state different than the last one? If so, return true.

Remember, we'll want to set presence to the new updated value. So each condition should update the presence value. For example:

*presence = NotHere;

Here's what the fully flushed out function looks like:

bool checkTileStateChanged( TilePresenceType *presence ) {

    // Check to see if it's here.
    if( millis() > lastSeen+TILE_NOT_HERE_MS ) {
        if( *presence != NotHere ) {
            *presence = NotHere;
            Log.trace("not here!");
            return true;
        }
    // Case if we've just started up
    } else if ( lastSeen == 0 ) {
        if( *presence != PresenceUnknown ) {
            *presence = PresenceUnknown;
            Log.trace("unknown!");
            return true;
        }
    // Case if lastSeen is < TILE_NOT_HERE_MS
    } else {
        if( *presence != Here ) {
            *presence = Here;
            Log.trace("here!");
            return true;
        }
    }

    return false;
}

We can now use this function in the main loop underneath the timer to start Ble.scan(). We can use it to send a JSON payload. In this case we'll include important information like the Bluetooth Address, lastSeen data, lastRSSI data and a message.

// If we have a change
if( checkTileStateChanged(&present) ) {

}

We'll use an array of char to get our address in a string format. You can chain together toString() with toCharArray to get what we need.

// Get the address string
char address[18];
searchAddress.toString().toCharArray(address,sizeof(address));

An example payload string could look something like this:

// Create payload
status = String::format("{\"address\":\"%s\",\"lastSeen\":%d,\"lastRSSI\":%i,\"status\":\"%s\"}",
    address, lastSeen, lastRSSI, messages[present]);

status is simply a String defined at the top of the file:

// The payload going to the cloud
String status;

You notice that there's also a variable called messages. This is a static const array of strings. They're mapped to the values from the TilePresenceType. Here's what it looks like

const char * messages[] {
    "unknown",
    "here",
    "not here"
};

That way PresenceUnknown matches to "unknown", Here matches to "here", etc. It's a cheap easy way to associate a string with an enum.

Finally we'll publish and process. This allows us to send the update immediately.

// Publish the RSSI and Device Info
Particle.publish("status", status, PRIVATE, WITH_ACK);

// Process the publish event immediately
Particle.process();

The overall function should look something like this in the end:

// If we have a change
if( checkTileStateChanged(&present) ) {

    // Get the address string
    char address[18];
    searchAddress.toString().toCharArray(address,sizeof(address));

    // Create payload
    status = String::format("{\"address\":\"%s\",\"lastSeen\":%d,\"lastRSSI\":%i,\"status\":\"%s\"}",
        address, lastSeen, lastRSSI, messages[present]);

    // Publish the RSSI and Device Info
    Particle.publish("status", status, PRIVATE, WITH_ACK);

    // Process the publish event immediately
    Particle.process();

}

Now, let's test it!

Testing it!

We can test to make sure our Publish events are occurring without event leaving Particle Workbench. Open a new terminal by going to View → Terminal. Then use the following command:

particle subscribe --device <device_name> <event_name>

Replace <device_name> with the name or ID of your device.

Replace <event_name> with the name of the event. In our case it's status.

You can then test it all by removing the battery and waiting for the "not here" alert. Plug the battery back in and you should get a "here" alert.

Here's an example of the output

> particle subscribe --device hamster_turkey status

Subscribing to "status" from hamster_turkey's stream
Listening to: /v1/devices/hamster_turkey/events/status
{"name":"status","data":"{\"address\":\"C0:A5:0C:FE:E7:D7\",\"lastSeen\":40154002,\"lastRSSI\":-82,\"status\":\"not here\"}","ttl":60,"published_at":"2019-09-07T02:29:42.232Z","coreid":"e00fce68d36c42ef433428eb"}
{"name":"status","data":"{\"address\":\"C0:A5:0C:FE:E7:D7\",\"lastSeen\":40193547,\"lastRSSI\":-83,\"status\":\"here\"}","ttl":60,"published_at":"2019-09-07T02:29:50.352Z","coreid":"e00fce68d36c42ef433428eb"}

Configuring Webhook

In the last part of this tutorial we'll set up push notifications using a webhook. As mentioned before, we'll use Pushover and their handy API to send push notification(s) to the device(s) of your choice.

Pushover has a fantastically easy API to use. Their application is a Swiss army knife for situations where you don't want to code an app to send push notifications.

The first thing that you'll have to take note is your user key. You can get that by logging into Pushover. Note: you'll need to set up an account first if you haven't already.

It should look something like this:

If you're logged in and don't see this page, click on the Pushover logo and that should bring you back.

Next we'll want to create an application. Click on the Apps & Plugins at the top of the screen.

You should then click Create a New Application. This will allow us to get an API Token that will be needed in the Particle Webhook setup.

Set a name as you see fit. Fill in the description if you want a reminder. Click the box and then click Create Application.

You should go to the next page. Copy and save the API Token/Key we'll need this also in a few steps.

Now, let's setup the Webhook. Jump over to https://console.particle.io and create a new integration.

We'll set the Event Name to status.

The URL to https://api.pushover.net/1/messages.json

Also, if you want to filter by a specific device make sure you select it in the Device dropdown.

Under Advanced Settings we'll finish up by setting a few fields.

Create the following fields: token, user, title, and message. Then set token to the API Token we got earlier. Do the same for the User Key.

The title will show up as the title of your message. Make it whatever makes sense for you.

You can set the message as The Tile is currently {{{status}}}. RSSI: {{{lastRSSI}}}.

We are using mustache templates here. They allow you to use the data in the published payload and reformat it to your liking. In our case, we're using them to "fill in the blanks." The message once processed would look something like this:

The Tile is currently here. RSSI: -77

As a side note, i'll be talking more about these templates in my guide. So stay tuned for that!

Test it

Once your integration is in place, you can test doing what we did in the earlier step. Remove the battery, and wait for the "not here" message. Put it back and wait for the "here" message.

Here's what it would look like on an iPhone:

As you can see, I tested it a bunch! ?

If you've made it this far and everything is working, great work. You now have a Tile tracker for your house, office or wherever.

The Code

Looking for the finished code for this example? I would be too! It's hosted on Github and is available here.

Conclusion

As you can imagine, the techniques and technologies used in this article can be used in many ways. Let's summarize some of the key take aways:

1. Using Bluetooth Central to scan for and identify an off-the-shelf Tile device
2. Storing the Tile identifying information to EEPROM. That way it can be retrieved on startup.
3. Using our familiar Particle.publish to push updates to the cloud.
4. Using a Particle Integration Webhook to create push notifications on state change.

Now that you have it all working, expand on it, hack it and make it yours. Oh and don't forget to share! I'd love to hear from you. hello@jaredwolff.com

Like this post? Click one of the share links below and share it with the world. :)

This is a cross post from my blog. You can check out the original here.

Interested in learning more? I'm writing a guide on how to get the most out of the Particle Platform. Learn more about it here.

In a previous tutorial, you learned how to add Bluetooth to a Particle Xenon application. That way you could control the onboard RGB LED from a test app like nRF Connect or Light Blue Explorer.

In this post, we're going to take it one step further. We're going to develop a Swift app to control a Particle Mesh RGB led. If all goes well, you should have a working app in about 20 minutes!

Let's get started.

Don't have time right now to read the full article?

Download the PDF version here.

Getting set up

• Install Xcode. You can download it from the App store here.
• You'll also need an Apple login. I use my iCloud email. You can create a new account within Xcode if you don't have one yet.
• Install the RGB example code on a Particle Mesh board.

Create the project

Once everything is installed, let's get to the fun stuff!

Open Xcode and go to File → New Project.

Select Single View App.

Then update the Project Name to be to your liking. I've also changed my organization identifier to com.jaredwolff. Modify it as you see fit!

Select a location to save it.

Next find your Info.plist.

Update info.plist by adding Privacy - Bluetooth Peripheral Usage Description

The description I ended up using was App uses Bluetooth to connect to the Particle Xenon RGB Example

This allows you to use Bluetooth in your app if you ever want to release it.

Now, let's get everything minimally functional!

Minimally functional

Next, we'll get a minimally functional app to connect and do a services discovery. Most of the action will happen in the ViewController.swift.

Lets first import CoreBluetooth

    import CoreBluetooth

This allows us to control the Bluetooth Low Energy functionality in iOS. Then let's add both the CBPeripheralDelegate and CBCentralManagerDelegate to the ViewController class.

    class ViewController: UIViewController, CBPeripheralDelegate, CBCentralManagerDelegate {

Let's now create local private variables to store the actual central manager and peripheral. We'll set them up further momentarily.

    // Properties
    private var centralManager: CBCentralManager!
    private var peripheral: CBPeripheral!

In your viewDidLoad function, let's init the centralManager

    centralManager = CBCentralManager(delegate: self, queue: nil)

Setting delegate: self is important. Otherwise the central state never changes on startup.

Before we get further, let's create a separate file and call it ParticlePeripheral.swift. It can be placed anywhere but I placed it in a separate 'group' called Models for later.

Inside we'll create some public variables which contain the UUIDs for our Particle Board. They should look familiar!

    import UIKit
    import CoreBluetooth

    class ParticlePeripheral: NSObject {

        /// MARK: - Particle LED services and charcteristics Identifiers

        public static let particleLEDServiceUUID     = CBUUID.init(string: "b4250400-fb4b-4746-b2b0-93f0e61122c6")
        public static let redLEDCharacteristicUUID   = CBUUID.init(string: "b4250401-fb4b-4746-b2b0-93f0e61122c6")
        public static let greenLEDCharacteristicUUID = CBUUID.init(string: "b4250402-fb4b-4746-b2b0-93f0e61122c6")
        public static let blueLEDCharacteristicUUID  = CBUUID.init(string: "b4250403-fb4b-4746-b2b0-93f0e61122c6")

    }

Back in ViewController.swift let's piece together the Bluetooth bits.

Bluetooth bits

Everything to do with Bluetooth is event based. We'll be defining several functions that handle these events. Here are the important ones:

centralManagerDidUpdateState updates when the Bluetooth Peripheral is switched on or off. It will fire when an app first starts so you know the state of Bluetooth. We also start scanning here.

The centralManager didDiscover event occurs when you receive scan results. We'll use this to start a connection.

The centralManager didConnect event fires once the device is connected. We'll start the device discovery here. Note: Device discovery is the way we determine what services and characteristics are available. This is a good way to confirm what type of device we're connected to.

The peripheral didDiscoverServices event first once all the services have been discovered. Notice that we've switched from centralManager to peripheral now that we're connected. We'll start the characteristic discovery here. We'll be using the RGB service UUID as the target.

The peripheral didDiscoverCharacteristicsFor event will provide all the characteristics using the provided service UUID. This is the last step in the chain of doing a full device discovery. It's hairy but it only has to be done once during the connection phase!

Defining all the Bluetooth functions.

Now that we know what the functions events that get triggered. We'll define them in the logical order that they happen during a connection cycle.

First, we'll define centralManagerDidUpdateState to start scanning for a device with our Particle RGB LED Service. If Bluetooth is not enabled, it will not do anything.

    // If we're powered on, start scanning
        func centralManagerDidUpdateState(_ central: CBCentralManager) {
            print("Central state update")
            if central.state != .poweredOn {
                print("Central is not powered on")
            } else {
                print("Central scanning for", ParticlePeripheral.particleLEDServiceUUID);
                centralManager.scanForPeripherals(withServices: [ParticlePeripheral.particleLEDServiceUUID],
                                                  options: [CBCentralManagerScanOptionAllowDuplicatesKey : true])
            }
        }

Defining the centralManager didDiscover is our next step in the process. We know we've found a device if this event has occurred.

    // Handles the result of the scan
        func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) {

            // We've found it so stop scan
            self.centralManager.stopScan()

            // Copy the peripheral instance
            self.peripheral = peripheral
            self.peripheral.delegate = self

            // Connect!
            self.centralManager.connect(self.peripheral, options: nil)

        }

So, we stop scanning using self.centralManager.stopScan(). We set the peripheral so it persists through the app. Then we connect to that device using self.centralManager.connect

Once connected, we need to double check if we're working with the right device.

    // The handler if we do connect succesfully
        func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
            if peripheral == self.peripheral {
                print("Connected to your Particle Board")
                peripheral.discoverServices([ParticlePeripheral.particleLEDServiceUUID])
            }
        }

By comparing the two peripherals we'll know its the device we found earlier. We'll kick off a services discovery using peripheral.discoverService. We can use ParticlePeripheral.particleLEDServiceUUID as a parameter. That way we don't pick up any services we don't care about.

Once we finish the discovering services, we'll get a didDiscoverServices event. We iterate through all the "available" services. (Though there will only be one!)

    // Handles discovery event
        func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
            if let services = peripheral.services {
                for service in services {
                    if service.uuid == ParticlePeripheral.particleLEDServiceUUID {
                        print("LED service found")
                        //Now kick off discovery of characteristics
                        peripheral.discoverCharacteristics([ParticlePeripheral.redLEDCharacteristicUUID,
                                                                 ParticlePeripheral.greenLEDCharacteristicUUID,
                                                                 ParticlePeripheral.blueLEDCharacteristicUUID], for: service)
                        return
                    }
                }
            }
        }

By this point this is the third time we're checking to make sure we have the correct service. This becomes more handy later when there are many characteristics and many services.

We call peripheral.discoverCharacteristics with an array of UUIDs for the characteristics we're looking for. They're all the UUIDs that we defined in ParticlePeripheral.swift.

Finally, we handle the didDiscoverCharacteriscsFor event. We iterate through all the available characteristics. As we iterate we compare with the ones we're looking for.

    // Handling discovery of characteristics
        func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
            if let characteristics = service.characteristics {
                for characteristic in characteristics {
                    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
                        print("Red LED characteristic found")
                    } else if characteristic.uuid == ParticlePeripheral.greenLEDCharacteristicUUID {
                        print("Green LED characteristic found")
                    } else if characteristic.uuid == ParticlePeripheral.blueLEDCharacteristicUUID {
                        print("Blue LED characteristic found");
                    }
                }
            }
        }

At this point we're ready to do a full device discovery of our Particle Mesh device. In the next section we'll test what we have to make sure things are working ok.

Testing our minimal example

Before we get started, if you run into trouble I've put some troubleshooting steps in the footnotes.

To test, you'll have to have an iPhone with Bluetooth Low Energy. Most modern iPhones have it. The last iPhone not to have it I believe was either the iPhone 4 or 3Gs. (so you're likely good)

First, plug it into your computer.

Go to the top by the play and stop buttons. Select your target device. In my case I chose my phone (Jared's iPhone). You can also use an iPad.

Then you can hit Command + R or hit that Play button to load the app to your phone.

Make sure you have your log tab open. Enable it by clicking the bottom pane button in the top right corner.

Make sure you have a mesh device setup and running the example code. You can go to this post to get it. Remember your Particle Mesh board needs to be running device OS 1.3.0 or greater for Bluetooth to work!

Once both the firmware and app is loaded, let's check the log output.

It should look something like this:

View loaded
Central state update
Central scanning for B4250400-FB4B-4746-B2B0-93F0E61122C6
Connected to your Particle Board
LED service found
Red LED characteristic found
Green LED characteristic found
Blue LED characteristic found

This means that your Phone has connected, found the LED service! The characteristics also being discovered is important here. Without those we wouldn't be able to send data to the mesh device.

Next step is to create some sliders so we can update the RGB values on the fly.

Slide to the left. Slide to the right.

Next we're going to add some elements to our Main.storyboard. Open Main.storyboard and click on the View underneath View Controller.

Then click on the Library button. (It looks like the old art Apple used for the home button)

You'll get a pop-up with all the choices that you can insert into your app.

Drag three Labels and copy three Sliders to your view.

You can double click on the labels and rename them as you go.

If you click and hold, some handy alignment tools will popup. They'll even snap to center!

You can also select them all and move them together. We'll align them vertically and horizontally.

In order for them to stay in the middle, let's remove the autoresizing property. Click the Ruler icon on the top right. Then click each of the red bars. This will ensure that your labels and sliders stay on the screen!

Next let's click the Show Assistant Editor button. (Looks like a Venn diagram)

Note: make sure that ViewController.swift is open in your Assistant Editor.

Then underneath the /properties section, Control-click and drag the Red Slider into your code.

Repeat with all the other ones. Make sure you name them something different. Your code should look like this when you're done:

        // Properties
        private var centralManager: CBCentralManager!
        private var peripheral: CBPeripheral!

        // Sliders
        @IBOutlet weak var redSlider: UISlider!
        @IBOutlet weak var greenSlider: UISlider!
        @IBOutlet weak var blueSlider: UISlider!

This allow us to access the value of the sliders.

Next, let's attach the Value Changed event to each of the sliders. Right click on the Red Slider in the folder view.

It should give you some options for events. Click and drag the Value Changed event to your code. Make sure you name it something that makes sense. I used RedSliderChanged for the Red Slider.

Repeat two more times. Your code should look like this at the end of this step:

        @IBAction func RedSliderChanged(_ sender: Any) {
        }

        @IBAction func GreenSliderChanged(_ sender: Any) {
        }

        @IBAction func BlueSliderChanged(_ sender: Any) {
        }

I've also selected each of the sliders to and un-checked Enabled. That way you can't move them. We'll enable them later on in code.

Also, this is a great time to change the maximum value to 255. Also set the default value from 0.5 to 0.

Back at the top of the file. Let's create some local variables for each of the characteristics. We'll use these so we can write the slider variables to the Particle Mesh board.

        // Characteristics
        private var redChar: CBCharacteristic?
        private var greenChar: CBCharacteristic?
        private var blueChar: CBCharacteristic?

Now, let's tie everything together!

In the didDiscoverCharacteristicsFor callback function. Let's assign those characteristics. For example

    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
        print("Red LED characteristic found")
        redChar = characteristic

As we find each characteristic, we can also enable each of the sliders in the same spot.

            // Unmask red slider
            redSlider.isEnabled = true

In the end your didDiscoverCharacteristicsFor should look like:

    // Handling discovery of characteristics
        func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
            if let characteristics = service.characteristics {
                for characteristic in characteristics {
                    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
                        print("Red LED characteristic found")

                        redChar = characteristic
                        redSlider.isEnabled = true
                    } else if characteristic.uuid == ParticlePeripheral.greenLEDCharacteristicUUID {
                        print("Green LED characteristic found")

                        greenChar = characteristic
                        greenSlider.isEnabled = true
                    } else if characteristic.uuid == ParticlePeripheral.blueLEDCharacteristicUUID {
                        print("Blue LED characteristic found");

                        blueChar = characteristic
                        blueSlider.isEnabled = true
                    }
                }
            }
        }

Now, let's update the RedSliderChanged GreenSliderChanged and BlueSliderChanged functions. What we want to do here is update the characteristic associated with the Changed function. I created a separate function called writeLEDValueToChar. We'll pass in the characteristic and the data.

    private func writeLEDValueToChar( withCharacteristic characteristic: CBCharacteristic, withValue value: Data) {

            // Check if it has the write property
            if characteristic.properties.contains(.writeWithoutResponse) && peripheral != nil {

                peripheral.writeValue(value, for: characteristic, type: .withoutResponse)

            }

        }

Now add a call to writeLEDValueToChar to each of the Changed functions. You will have to cast the value to a Uint8. (The Particle Mesh device expects an unsigned 8-bit number.)

            @IBAction func RedSliderChanged(_ sender: Any) {
            print("red:",redSlider.value);
            let slider:UInt8 = UInt8(redSlider.value)
            writeLEDValueToChar( withCharacteristic: redChar!, withValue: Data([slider]))

        }

Repeat this for GreenSliderChanged and BlueSliderChanged. Make sure you changed red to green and blue for each!

Finally, to keep things clean, i've also added a function that handles Bluetooth disconnects.

    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) {

Inside, we should reset the state of the sliders to 0 and disable them.

            if peripheral == self.peripheral {
                print("Disconnected")

                redSlider.isEnabled = false
                greenSlider.isEnabled = false
                blueSlider.isEnabled = false

                redSlider.value = 0
                greenSlider.value = 0
                blueSlider.value = 0

It's a good idea to reset self.peripheral to nil that way we're not ever trying to write to a phantom device.

                self.peripheral = nil

Finally, because we've disconnected, start scanning again!

                // Start scanning again
                print("Central scanning for", ParticlePeripheral.particleLEDServiceUUID);
                centralManager.scanForPeripherals(withServices: [ParticlePeripheral.particleLEDServiceUUID],
                                                  options: [CBCentralManagerScanOptionAllowDuplicatesKey : true])
            }

Alright! We just about ready to test. Let's move on to the next (and final) step.

Test the sliders.

The hard work is done. Now it's time to play!

The easiest way to test everything is to click the Play button in the top left or the Command + R keyboard shortcut. Xcode will load the app to your phone. You should see a white screen proceeded by a screen with your sliders!

The sliders should stay greyed out until connected to your Particle Mesh board. You can check your log output if the connection has been established.

View loaded
Central state update
Central scanning for B4250400-FB4B-4746-B2B0-93F0E61122C6
Connected to your Particle Board
LED service found
Red LED characteristic found
Green LED characteristic found
Blue LED characteristic found

(Look familiar? We're connected!)

If you followed everything perfectly, you should be able to move the sliders. Better yet, the RGB LED on the Particle Mesh board should change color.

Conclusion

In this article you've learned how to connect your Particle Mesh board and iOS device over Bluetooth. We've learned how to connect to each of the available characteristics. Plus, on top of it all, make a clean interface to do it all in.

As you can imagine, you can go down the rabbit hole with Bluetooth on iOS. There's more coming in my upcoming guide: The Ultimate Guide to Particle Mesh. Subscribers to my list get access to pre-launch content and a discount when it comes out! Click here to get signed up.

Code

The full source code is available on Github. If you find it useful, hit the star button. ⭐️

This post is originally from my blog on www.jaredwolff.com.

Writing an app takes time. It takes even more time to write one that works with hardware.

Luckily there's a solution to this problem.

Enter Blynk.

It's an app that connects to your hardware. It has a drag and drop interface with pre built widgets. That means you can build an app in seconds. Then upload your device sensors readings within minutes.

Blynk does work with Argon, Boron or ethernet connected Xenon. Unfortunately it doesn't work over a Particle Mesh network. In this article you'll learn some of the workarounds to get your mesh based projects up an running.

From Particle Cloud to Blynk

Let's start with the most simple use case: getting data from any Particle Device to Blynk.

The Air Quality data from Particle Squared is perfect for this example. So, i'll be using that.

First let's create a new Blynk Project

Grab the Auth Token we'll need that in a bit. You can tap the Auth Token to copy it to your clipboard.

Next, let's add a SuperChart for this example.

Configure the SuperChart to use a Virtual Pin. We don't have access to the actual hardware pins on the device. V0 is a good choice.

To update values in Blynk, we'll have to connect somehow. The best way is to use an Integration in the Particle Console.

In Particle Console, click the icon below the terminal icon. Then click on New Integration.

Look at the example below to see how I filled everything out.

Particle Squared uses the Event Name as **blob. For other projects this may be different. Remember:** your event name is the same as from Particle.publish(eventName, data).

The URL is set to use the blink-cloud.com address. According to their API a sample URL looks like:

I'll also include it here so it's easier to copy

http://blynk-cloud.com/auth_token/update/pin?value=value

Replace auth_token with the Auth Token we got earlier.

Replace pin with the virtual pin we want to modify. In this case V0

Replace the value with the value you want to use.

We'll reference one of the values in the Particle Squared blob. It's organized like this:

{
  "temperature": 28.60,
  "humidity": 45.00,
  "sgp30_tvoc": 18,
  "sgp30_c02": 400,
  "bme680_temp": 27.36,
  "bme680_pres": 1012.43,
  "bme680_hum": 43.80,
  "bme680_iaq": 43.90,
  "bme680_temp_calc": 27.30,
  "bme680_hum_calc": 43.97
}

Particle uses mustache templates. As you can see in the screenshot above, you can set value to {{{temperature}}}.

Note: If you're working on your own project, it's important to publish with JSON. As a reference the Particle.publish command looks like:

// Publish data
Particle.publish("blob", String::format("{\"temperature\":%.2f,\"humidity\":%.2f}",si7021_data.temperature, si7021_data.humidity) , PRIVATE, WITH_ACK);

Click the big blue Save button at the bottom of the screen. Then we can move on to the next step!

Testing

Since creating our Particle Webhook Integration, it's been publishing data to Blynk. Let's go see if it's working.

First, let's go back to the Blynk app. Hit the Play Button in the top Right in Blynk screen.

If your integration has been running for a while, you should see the graph populate with data! In the case you don't see anything, let's check the logs.

Go back to your integration and scroll towards the bottom. We want to see if there are any errors.

Not sure what that looks like? Here's an example of an integration with errors:

You can scroll further down to investigate why the error has occurred.

All the way at the bottom shows the response from the server. Depending on the service, they'll give you information why your API call failed. In my case, I was missing values for two fields.

Particle to Blynk is working!

You now have a basic way of publishing to a virtual pin in Blynk. There are drawbacks though. Most importantly, you'll have to create an integration for every signal virtual pin. If you have eight readings, that means eight integrations.

Bummer.

In the next section, you'll learn a different way to configure Blynk. Let's go!

Local Mesh Using Blynk Library

Unlike the first method, we'll be focusing on changing firmware only.

We’ll use a Argon, Boron or Ethernet Connected Xenon and one regular Xenon. For the rest of this tutorial, we'll call these devices an “edge router”.

The Xenon will run the Particle Squared code. Instead of using Particle.publish we'll be using Mesh.publish. This allows us to publish only to the local mesh network.

Meanwhile the edge router is listening for the message. It collects the values and then uses the Blynk API to publish to the app.

Here are the steps:

Setup our Edge Router

Pull up the menu by pressing Cmd+Shift+P. Type Install Library.

Then enter blynk. The library should download if you haven't already.

Once installed you can include the library at the top of your .ino file like so:

#include <blynk.h>

In our setup() function let's init the Blynk library:

// Put initialization like pinMode and begin functions here.
Blynk.begin(auth);

In our setup() function, subscribe to the temperature event. The connected Xenon will generate this event.

// Subscribe to temperature events
Mesh.subscribe("temperature",tempHandler);

Define tempHandler like this for now:

// Temperature event handler for mesh
void tempHandler(const char *event, const char *data){
}

In the loop() function make sure we have Blynk.run();

// loop() runs over and over again, as quickly as it can execute.
void loop() {
  // The core of your code will likely live here.
  Blynk.run();
}

Finally, for tempHandler we can add a debug print to monitor events. I've used something like this:

Serial.printlnf("event=%s data=%s", event, data ? data : "NULL");

Particle uses this in some of their examples. It's perfect for our purposes as well!

Note: make sure you have Serial.begin() called in your Setup() function!

So now we have tempHandler to receive data from the Xenon. The edge router can now take that data and upload it to Blynk. Let's use the Blynk.virtualWrite function for this:

// Write the data
Blynk.virtualWrite(V0, data);

This will write the temperature value from a Xenon to the V0 pin. If you used something other than V0, be sure to change that value here. (This is the same setup as the previous Particle Cloud to Blynk example)

The final code for the edge router should look something like this. Compile a flash it to your device when you're ready!

/*
 * Project blynk-argon-forwarder
 * Description: Argon Blynk forwarder for Particle Mesh. Forwards data from mesh connected devices to Blynk.
 * Author: Jared Wolff
 * Date: 7/25/2019
 */

#include <blynk.h>

char auth[] = "<ENTER YOUR AUTH KEY>";

// Temperature event handler for mesh
void tempHandler(const char *event, const char *data){
  Serial.printlnf("event=%s data=%s", event, data ? data : "NULL");

  // Write the data
  Blynk.virtualWrite(V0, data);
}

// setup() runs once, when the device is first turned on.
void setup() {

  // Serial for debugging
  Serial.begin();

  // Put initialization like pinMode and begin functions here.
  Blynk.begin(auth);

  // Subscribe to temperature events
  Mesh.subscribe("temperature",tempHandler);

}

// loop() runs over and over again, as quickly as it can execute.
void loop() {
  // The core of your code will likely live here.
  Blynk.run();

}

Remember to set auth using the AUTH TOKEN in the Blynk app!

Setting up a Xenon

Create a new project. This time it will be for the Xenon capturing "temperature data."

Let's add a variable called time_millis to the top of the file. The type is system_tick_t. We'll use it to create a simple delay timer for the temperature readings.

// Global variable to track time (used for temp sensor readings)
system_tick_t time_millis;

For the interval, let's use a preprocessor define

#define INTERVAL_MS 2000

Now let's tie those together in the loop() function. We'll use an if statement to compare our current system time with that of the last event plus offset. If you ever need a simple timer, this is one of the best ways to do it!

// Check if our interval > 2000ms
  if( millis() - time_millis > INTERVAL_MS ) {
  }

Once we're inside, make sure you reset timer_millis:

        //Set time to the 'current time' in millis
    time_millis = millis();

Then, we'll generate the temperature value using the random() function. We'll use the two parameter variant. That way we can set the minimum value and the maximum value:

    // Create a random number
    int rand = random(20,30);

Finally we'll Mesh.publish the value:

    // Publish our "temperature" value
    Mesh.publish("temperature",String::format("%d",rand));

When this example runs, the temperature is broadcast to the mesh network. Then, the edge router receives it and forwards it on to Blynk!

You can flash this firmware whenever you're ready. Here's the full code for the Xenon so you can cross compare:

/*
 * Project blynk-xenon-rgb
 * Description: Recieve RGB level from connected Edge Router. Sends simiulated temperature values via mesh to the Blynk cloud.
 * Author: Jared Wolff
 * Date: 7/25/2019
 */

// How often we update the temperature
#define INTERVAL_MS 2000

// Global variable to track time (used for temp sensor readings)
system_tick_t time_millis;
// setup() runs once, when the device is first turned on.
void setup() {

  // Set time to 0
  time_millis = 0;

}

// loop() runs over and over again, as quickly as it can execute.
void loop() {

  // Check if our interval > 2000ms
  if( millis() - time_millis > INTERVAL_MS ) {
    //Set time to the 'current time' in millis
    time_millis = millis();

    // Create a random number
    int rand = random(20,30);

    // Publish our "temperature" value
    Mesh.publish("temperature",String::format("%d",rand));

  }

}

Give it a test!

Now that we've programmed both devices let's get them talking to each other.

I've already set up the Argon with a mesh network called 8f-9. I'll explain how to get the Xenon connected with the CLI. You can also used the Particle App.

First, let's connect the Xenon to USB and get it into Listening Mode. After connect, hold the Mode button until blinking blue.

Then use the CLI to set up the mesh network. First let's get the device ID:

Jareds-MacBook-Pro:nrfjprog.sh jaredwolff$ particle identify
? Which device did you mean?
  /dev/tty.usbmodem146401 - Argon
❯ /dev/tty.usbmodem146101 - Xenon

If you have multiple devices connect, make sure you select the right one! If prompted, select a device. Your output should look something like:

Your device id is e00fce682d9285fbf4412345
Your system firmware version is 1.3.0-rc.1

We'll need the id for the next step. Now, let's run the particle mesh command.

particle mesh add <xenon id> <id of your argon, boron, etc>

Here's an example below:

particle mesh add e00fce682d9285fbf4412345 hamster_turkey
? Enter the network password [hidden]
▄ Adding the device to the network...

At the end of it you'll see:

Done! The device should now connect to the cloud.

This process is not perfect. During the Adding the device to the network... stage, I had to remove the Xenon using particle mesh remove. Then re-run the particle mesh add command after resetting the Argon.

Now here comes to finale.

Connect the two devices to serial using particle serial monitor --follow

If you have the two devices connected, particle serial monitor will prompt you to select:

Jareds-MacBook-Pro:blynk-xenon-rgb jaredwolff$ particle serial monitor --follow
Polling for available serial device...
? Which device did you mean? /dev/tty.usbmodem146101 - Xenon
Opening serial monitor for com port: "/dev/tty.usbmodem146101"
Serial monitor opened successfully:

Remember: You have to run particle serial monitor for each device you want to connect to.

If all is working, you'll likely see some output from the edge router!

Serial monitor opened successfully:
event=temperature data=21
event=temperature data=28
event=temperature data=21
event=temperature data=27
event=temperature data=28
event=temperature data=26
event=temperature data=23
event=temperature data=26
event=temperature data=21

Looking at the app, the Super Chart should be reacting to this new data.

Compare the last value in the command line to the last on the chart? Do they match? If so, you made it to the end of this example!

Conclusion

In this tutorial you've learned how to forward Particle Cloud data to Blynk. You've also learned how to do the same using a Particle Argon, Boron or ethernet connected Xenon. Awe yea. ??

Now that you have the tools to Blink-ify your Particle Mesh powered projects, it's time to get to work!

Like this post?

This post is an excerpt from my upcoming Ultimate Guide to Particle Mesh. I'll be sharing more exclusive content with my mailing list as it get's closer to launch. You can sign up here for updates.

Still have questions?

Leave a comment or shoot me a line.

This post is originally from www.jaredwolff.com

I was defeated.

I had spent the whole night trying to get a Bluetooth Low Energy project working. It was painful. It was frustrating. I was ready to give up.

That was during the early days of Bluetooth Low Energy. Since then it's gotten easier and easier to develop. The Particle Mesh Bluetooth Library is no exception.

In this walkthrough, i'll show you how to use Particle's Bluetooth API. We'll configure some LEDs and watch them change over all devices in the Mesh network. We'll be using an Argon and Xenon board.

Ready? Let's get started!

P.S. this post is lengthy. If you want something to download, click here for a beautifully formatted PDF.

Stage 1: Setting Up Bluetooth

1. Download/Install Particle Workbench

2. Create a new Project. I picked a suitable location and then named it ble_mesh

   

3. Go to your /src/ direcory and open your <your project name>.ino file

4. Then make sure you change the version of your deviceOS to > 1.3.0

   

Write the Code

We want to set up a service with 3 characteristics. The characteristics relate to the intensity of the RGB LEDs respectively. Here's how to get your Bluetooth Set Up:

1. In your Setup() function enable app control of your LED

    RGB.control(true);
   

2. Set up your UUIDs at the top of your .ino file

   const char serviceUuid = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"; const char red = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"; const char green = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"; const char blue = "6E400004-B5A3-F393-E0A9-E50E24DCCA9E";

   UUIDs are unique identifiers or addresses. They're used to differentiate different services and characteristics on a device.

   The above UUIDs are used in previous Particle examples. If you want to create your own you can use uuidgen on the OSX command line. You can also go to a website like Online GUID Generator.

   

   Use the above settings to get your own UUID. You can then create your service and characteristic UUIDS from this generated one:

   const char serviceUuid = "b4250400-fb4b-4746-b2b0-93f0e61122c6"; //service const char red = "b4250401-fb4b-4746-b2b0-93f0e61122c6"; //red char const char green = "b4250402-fb4b-4746-b2b0-93f0e61122c6"; //green char const char blue = "b4250403-fb4b-4746-b2b0-93f0e61122c6"; //blue char

   There's no right or wrong way to do this. But you have to be careful you're not using the UUIDs reserved by the Bluetooth SIG. This is highly unlikely. If you do want to double check you can go here and here.

   For now, we'll stick with the first set of UUIDs.

3. In Setup(), initialize your service.

   // Set the RGB BLE service BleUuid rgbService(serviceUuid);

   This is the first step of "registering' your service. More on this below.

4. Initialize each characteristic in Setup()

   BleCharacteristic redCharacteristic("red", BleCharacteristicProperty::WRITE_WO_RSP, red, serviceUuid, onDataReceived, (void)red); BleCharacteristic greenCharacteristic("green", BleCharacteristicProperty::WRITE_WO_RSP, green, serviceUuid, onDataReceived, (void)green); BleCharacteristic blueCharacteristic("blue", BleCharacteristicProperty::WRITE_WO_RSP, blue, serviceUuid, onDataReceived, (void*)blue);

   For this setup, we're going to use the WRITE_WO_RSP property. This allows us to write the data and expect no response. I've referenced the UUIDs as the next two parameters. The first being the characteristic UUID. The second being the service UUID.

   The next parameter is the callback function. When data is written to this callback, this function will fire.

   Finally the last parameter is the context. What does this mean exactly? We're using the same callback for all three characteristics. The only way we can know which characteristic was written to (in deviceOS at least) is by setting a context. In this case we're going to use the already available UUIDs.

5. Right after defining the characteristics, let's add them so they show up:

   // Add the characteristics BLE.addCharacteristic(redCharacteristic); BLE.addCharacteristic(greenCharacteristic); BLE.addCharacteristic(blueCharacteristic);

6. Set up the callback function.

   // Static function for handling Bluetooth Low Energy callbacks static void onDataReceived(const uint8_t data, size_t len, const BlePeerDevice& peer, void context) {

   }

   You can do this at the top of the file (above Setup()) We will define this more later.

7. Finally, in order for your device to be connectable, we have to set up advertising. Place this code at the end of your Setup() function

   // Advertising data BleAdvertisingData advData;

   // Add the RGB LED service advData.appendServiceUUID(rgbService);

   // Start advertising! BLE.advertise(&advData);

   First we create a BleAdvertisingData object. We add the rgbService from Step 3. Finally, we can start advertising so our service and characteristics are discoverable!

Time to test

At this point we have a minimally viable program. Let's compile it and program it to our Particle hardware. This should work with any Mesh enabled device. (Xenon, Argon, Boron)

1. Before we start testing, temporarily add SYSTEM_MODE(MANUAL); to the top of your file. This will prevent the device connecting to the mesh network. If the device is blinking blue on startup, you'll have to set it up with the Particle App before continuing.

2. Download the 1.3.0-rc.1 image here. For Xenon, you'll need xenon-system-part1@1.3.0-rc.1.bin. For others look for boron-system-part1@1.3.0-rc.1.bin and argon-system-part1@1.3.0-rc.1.bin. The files are at the bottom of the page under Assets

   

3. Put your device into DFU mode. Hold the Mode Button and momentarily click the Reset Button. Continue holding the Mode Button until the LED blinks yellow.

4. In a command line window, change directories to where you stored the file you downloaded. In my case the command is cd ~/Downloads/

5. Then run:

   particle flash --usb xenon-system-part1@1.3.0-rc.1.bin

   This will install the latest OS to your Xenon. Once it's done it will continue to rapidly blink yellow. Again if you have a different Particle Mesh device, change the filename to match.

6. In Visual Code, use the Command + Shift + P key combination to pop up the command menu. Select Particle: Compile application (local)

   

7. Fix any errors that may pop up.

8. Then, open the same menu and select Flash application (local)

   

9. When programming is complete, pull out your phone. Then, open your favorite Bluetooth Low Energy app. The best ones are NRF Connect and Light Blue Explorer. I'm going to use Light Blue Explorer for this example.

10. Check if a device named "Xenon-" is advertising. Insert with the unique ID for your device.

    

11. Find your device and click the name.

12. Look at the list of services & characteristics. Does it include the service and characteristic UUID's that we have set so far? For instance, does the service UUID show up as 6E400001-B5A3-F393-E0A9-E50E24DCCA9E?

    

    If everything shows up as you expect, you're in a good place. If not go through the earlier instructions to make sure everything matches.

Stage 2: Handling Data

The next stage of our project is to process write events. We'll be updating our onDataReceived function.

Write the Code

1. First, let's create a struct that will keep the state of the LEDs. This can be done at the top of the file.

   // Variables for keeping state typedef struct { uint8_t red; uint8_t green; uint8_t blue; } led_level_t;

2. The second half of that is to create a static variable using this data type

   // Static level tracking static led_level_t m_led_level;

   The first two steps allows us to use one single variable to represent the three values of the RGB LED.

3. Next, let's check for basic errors inside the onDataReceive function For instance we want to make sure that we're receiving only one byte.

   // We're only looking for one byte if( len != 1 ) { return; }

4. Next, we want to see which characteristic this event came from. We can use the context variable to determine this.

   // Sets the global level if( context == red ) { m_led_level.red = data[0]; } else if ( context == green ) { m_led_level.green = data[0]; } else if ( context == blue ) { m_led_level.blue = data[0]; }

   Remember, in this case context will be equal to the pointer of either the red, green, or blue UUID string. You can also notice we're setting m_led_level. That way we can update the RGB led even if only one value has changed.

5. Finally, once set, you can write to the RGB object

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

Test the Code

Let's go through the same procedure as before to flash the device.

1. Put your device into DFU mode. Hold the Mode Button and click the Reset Button. Continue holding the Mode Button until the LED blinks yellow.

2. Then, open the same menu and select Flash application (local)

   

3. Once it's done programming, connect to the device using Light Blue Explorer.

4. Tap on the characteristic that applies to the red LED.

5. Write FF. The red LED should turn on.

   

   

6. Write 00. The red LED should turn off.

7. Do the same for the other two characteristics. We now have full control of the RGB LED over Bluetooth Low Energy!

Stage 3: Sharing Via Mesh

Finally, now that we're successfully receiving BLE message, it's time to forward them on to our mesh network.

Write the Code

1. First let's remove MANUAL mode. Comment out SYSTEM_MODE(MANUAL);

2. At the top of the file let's add a variable we'll used to track if we need to publish

   // Tracks when to publish to Mesh static bool m_publish;

3. Then initialize it in Setup()

   // Set to false at first m_publish = false;

4. Then, after setting the RGB led in the onDataReceived callback, let's set it true:

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

   // Set to publish m_publish = true;

5. Let's add a conditional in the loop() function. This will cause us to publish the LED status to the Mesh network:

   if( m_publish ) { // Reset flag m_publish = false;

   // Publish to Mesh Mesh.publish("red", String::format("%d", m_led_level.red)); Mesh.publish("green", String::format("%d", m_led_level.green)); Mesh.publish("blue", String::format("%d", m_led_level.blue)); }

   Mesh.publish requires a string for both inputs. Thus, we're using String::format to create a string with our red, green and blue values.

6. Then let's subscribe to the same variables in Setup(). That way another device can cause the LED on this device to update as well.

   Mesh.subscribe("red", meshHandler); Mesh.subscribe("green", meshHandler); Mesh.subscribe("blue", meshHandler);

7. Toward the top of the file we want to create meshHandler

   // Mesh event handler static void meshHandler(const char event, const char data) { }

8. In this application, we need the event parameter and data parameter. In order use them, we have to change them to a String type. That way we can use the built in conversion and comparison functions. So, inside the meshHandler function add:

   // Convert to String for useful conversion and comparison functions String eventString = String(event); String dataString = String(data);

9. Finally we do some comparisons. We first check if the event name matches. Then we set the value of the dataString to the corresponding led level.

   // Determine which event we recieved if( eventString.equals("red") ) { m_led_level.red = dataString.toInt(); } else if ( eventString.equals("green") ) { m_led_level.green = dataString.toInt(); } else if ( eventString.equals("blue") ) { m_led_level.blue = dataString.toInt(); } else { return; }

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

   Then at the end we set the new RGB color. Notice how I handle an unknown state by adding a return statement in the else section. It's always good to filter out error conditions before they wreak havoc!

Test the Code

1. Open the Particle App on your phone

2. Let's set up the Argon first. If it's not blinking blue, hold the mode button until it's blinking blue.

   

   Note: if you've already programmed the app, the LED will be off by default. Hold the mode button for 5 seconds and then continue.

3. Go through the pairing process. The app walks you though all the steps. Make sure you remember the Admin password for your mesh network.

   

   

   

   

4. Program an Argon with the latest firmware (1.3.0) (see Stage 1 - Time to Test - Step 2 for a reminder on how to do this)

5. Once rapidly blinking yellow, program the Argon with the Tinker app. You can download it at the release page.

6. Once we have a nice solid Cyan LED (connected to the Particle Cloud) we'll program the app. Use the Cloud Flash option in the drop down menu.

   

   As far as I can tell, Particle forces any device flashed locally into safe mode when connecting to the cloud. It may be my setup. Your mileage may vary here. Best to use Cloud Flash.

   Make sure you select the correct deviceOS version (1.3.0-rc1), device type (Argon) and device name (What you named it during setup)

7. Connect to the Xenon using the phone app

8. Connect the Xenon to your Mesh network using the phone app

9. Flash your Xenon using Cloud Flash. Use the name that you gave it during the phone app setup. As long as the device is connected to Particle Cloud or in safe mode (Purple LED), it should program.

   

   

10. Once connected, let's get to the fun part. Open up Light Blue Explorer. Connect to either the Argon or the Xenon.

    

11. Select one of the LED characteristics and change the value.

    

    The LED should change on all devices!

Final Code

Here's the final code with all the pieces put together. You can use this to make sure you put them in the right place!!

/*

• Project ble_mesh
• Description: Bluetooth Low Energy + Mesh Example
• Author: Jared Wolff

• Date: 7/13/2019 */

  //SYSTEM_MODE(MANUAL);

  // UUIDs for service + characteristics const char serviceUuid = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"; const char red = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"; const char green = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"; const char blue = "6E400004-B5A3-F393-E0A9-E50E24DCCA9E";

  // Set the RGB BLE service BleUuid rgbService(serviceUuid);

  // Variables for keeping state typedef struct { uint8_t red; uint8_t green; uint8_t blue; } led_level_t;

  // Static level tracking static led_level_t m_led_level;

  // Tracks when to publish to Mesh static bool m_publish;

  // Mesh event handler static void meshHandler(const char event, const char data) {

  // Convert to String for useful conversion and comparison functions String eventString = String(event); String dataString = String(data);

  // Determine which event we recieved if( eventString.equals("red") ) { m_led_level.red = dataString.toInt(); } else if ( eventString.equals("green") ) { m_led_level.green = dataString.toInt(); } else if ( eventString.equals("blue") ) { m_led_level.blue = dataString.toInt(); } else { return; }

  // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

  }

  // Static function for handling Bluetooth Low Energy callbacks static void onDataReceived(const uint8_t data, size_t len, const BlePeerDevice& peer, void context) {

  // We're only looking for one byte if( len != 1 ) { return; }

  // Sets the global level if( context == red ) { m_led_level.red = data[0]; } else if ( context == green ) { m_led_level.green = data[0]; } else if ( context == blue ) { m_led_level.blue = data[0]; }

  // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

  // Set to publish m_publish = true;

  }

  // setup() runs once, when the device is first turned on. void setup() {

  // Enable app control of LED RGB.control(true);

  // Init default level m_led_level.red = 0; m_led_level.green = 0; m_led_level.blue = 0;

  // Set to false at first m_publish = false;

  // Set the subscription for Mesh updates Mesh.subscribe("red",meshHandler); Mesh.subscribe("green",meshHandler); Mesh.subscribe("blue",meshHandler);

  // Set up characteristics BleCharacteristic redCharacteristic("red", BleCharacteristicProperty::WRITE_WO_RSP, red, serviceUuid, onDataReceived, (void)red); BleCharacteristic greenCharacteristic("green", BleCharacteristicProperty::WRITE_WO_RSP, green, serviceUuid, onDataReceived, (void)green); BleCharacteristic blueCharacteristic("blue", BleCharacteristicProperty::WRITE_WO_RSP, blue, serviceUuid, onDataReceived, (void*)blue);

  // Add the characteristics BLE.addCharacteristic(redCharacteristic); BLE.addCharacteristic(greenCharacteristic); BLE.addCharacteristic(blueCharacteristic);

  // Advertising data BleAdvertisingData advData;

  // Add the RGB LED service advData.appendServiceUUID(rgbService);

  // Start advertising! BLE.advertise(&advData); }

  // loop() runs over and over again, as quickly as it can execute. void loop() {

  // Checks the publish flag, // Publishes to a variable called "red" "green" and "blue" if( m_publish ) {

  // Reset flag m_publish = false;

  // Publish to Mesh Mesh.publish("red", String::format("%d", m_led_level.red)); Mesh.publish("green", String::format("%d", m_led_level.green)); Mesh.publish("blue", String::format("%d", m_led_level.blue)); }

  }

Conclusion

In this tutorial you learned how to add Bluetooth to a Particle Mesh project. As you can imagine, the possibilities are endless. For instance you can add user/administrative apps into the experience. Now that's awesome. ?

You can expect more content like this in my upcoming book: The Ultimate Guide to Particle Mesh. Subscribe to my list for updates and insider content. Plus all early subscribers get a discount when it's released! Click here to sign up.