Create a .service file under /etc/systemd/system. For my outlet service, I created /etc/systemd/system/outlet.service and added the following:

[Service]
WorkingDirectory=/home/pi/Documents/Repos/outlet-device
ExecStart=/usr/local/bin/npm start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=notell
User=root
Group=root
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Helpful commands

sudo systemctl enable outlet - enables the service which will start on reboot

sudo systemctl disable outlet - disables the service, preventing it from starting on reboot

sudo systemctl start outlet - starts the service immediately

sudo systemctl stop outlet - stops the service, but the service will restart on reboot if it is still enabled

This post is going to build on those to demonstrate how we can build a Home Automation IoT platform that will allow us to view telemetry data from our devices and also manage our devices from a webpage or mobile application.

At the end of this post, we will have the following solution:

Azure Functions for message ingress and egress

At this point, we should have a pretty good handle on the IoT Hub and SignalR Service. What we need to do is get them talking to each other. The easiest way to do this is with Azure Functions. We can use the same Azure Functions project we set up previously.

We are going to need functions for two purposes:

• cloud-to-device messaging - these are messages to configure our device or put it into a particular state
• device-to-cloud messaging - these are the telemetry messages we want our mobile and web clients to display

Add local settings

We'll need to add a connection string to our IoT Hub Event Hub-compatible endpoint. Open you IoT Hub in the Azure portal and open the "Built-in endpoints" menu item. This will expose the endpoint we will connect our reader function to.

We will also need a connection string to the IoT Hub device registry so we can direct messages to our device. We need a policy that has both registry write and service connect permissions. I'm going to use the iothubowner policy, but as a best practice a new policy should be created with just those permissions.

Open local.settings.json and add the following to the Values property:

"Values": {
  ...
  "IoTHubConnectionString": "Endpoint=sb://...",
  "IoTHubRegistryConnectionString": "HostName=..."

Device-to-cloud messaging

For this flow, we are going to create an Azure Function that will read messages off our IoT Hub, massage them a bit and then send them on to SignalR Service.

As done previously, we'll create a new Azure Function but instead of using the HTTP Trigger template, we are going to use the Azure Event Hub trigger template. IoT Hub and Event Hub share the same technology for message ingress, so this trigger will be compatible for us. Name the function deviceToCloud.

Edit deviceToCloud's function.json

We are going to declaratively configure a couple bindings. The eventHubTrigger will already be in there, just ensure that the "connection": "IoTHubConnectionString" entry is in there so the function can connect to the IoT Hub endpoint we specified in our local.settings.json.

We will add a second output binding to push messages to SignalR Service, specifying the chat hub.

{
  "bindings": [
    {
      "type": "eventHubTrigger",
      "name": "eventHubMessages",
      "direction": "in",
      "eventHubName": "ServerlessIoTHub",
      "connection": "IoTHubConnectionString",
      "cardinality": "many",
      "consumerGroup": "$Default"
    },
    {
      "type": "signalR",
      "name": "signalRMessages",
      "hubName": "chat",
      "direction": "out"
    }
  ],
  "scriptFile": "../dist/deviceToCloud/index.js"
}

Edit deviceToCloud's index.ts

We need to write some code that will take each message and interrogate it for the id of the device that published it. We will then push that message along to SignalR Service using the device id as the group name.

Any client interested in observing a device's telemetry will simply need to join the SignalR group based on its id. Then SignalR will invoke the client's local handler and pass in the message (in this case, we expect the client to have a handler registered for handleMessage)

import { AzureFunction, Context } from "@azure/functions";

interface DeviceMessage {
  deviceId: string;
  [key: string]: any;
}

const eventHubTrigger: AzureFunction = async function(
  context: Context,
  eventHubMessages: DeviceMessage[]
): Promise<void> {
  context.log(
    `Eventhub trigger function called for message array ${eventHubMessages}`
  );

  eventHubMessages.forEach(message => {
    context.bindings.signalRMessages = [
      {
        // message will only be sent to this group
        groupName: message.deviceId,
        target: "handleMessage",
        arguments: [message]
      }
    ];
  });
};

export default eventHubTrigger;

Cloud-to-device messaging

For this flow, we are going to create an Azure Function that will take some message that includes the id of the device of interest, and then push it into the IoT Hub where it will then be routed to that device. We are going to leverage Device Twin Desired Properties as we have done previously to manage our devices' state.

Also as done previously, we'll create a new Azure Function using the HTTP Trigger template. Name it cloudToDevice.

Edit cloudToDevice's function.json

Just remove the get from the list of acceptable methods:

"methods": [
  "post"
 ]

Edit cloudToDevice's index.ts

Because there is no Device Twin binding, we are going to have to write a fair bit of code. We need to:

• retrieve the id of the device we want to send a message to from the querystring
• connect to our IoT Hub device registry
• get our device twin from the registry
• patch our device twin's desired property based on the incoming message

import { AzureFunction, Context, HttpRequest } from "@azure/functions";
import { Registry, Twin } from "azure-iothub";

const httpTrigger: AzureFunction = async function(
  context: Context,
  req: HttpRequest
): Promise<void> {
  const deviceId = req.query.deviceId;

  if (!deviceId) {
    context.res = {
      status: 400,
      body: "No device id in the request"
    };
    return;
  }

  const registry = Registry.fromConnectionString(process.env.IoTHubRegistryConnectionString);

  // Using the callback form of getTwin is not possible due to the need
  // to await so that I can call context.log before the function returns
  const getTwinResponse = await registry.getTwin(deviceId)
    .catch(getTwinErr => {
      context.res = {
        status: 400,
        body: `Could not retrieve device twin for device with Id ${deviceId}`
      };
      context.log(getTwinErr.message);
      throw getTwinErr;
    });

  // responseBody is presently typed incorrectly as HttpResponse<any>,
  // forcing this cast
  const twin = getTwinResponse.responseBody as Twin;
  const propertyPatch = {
    properties: {
      desired: req.body
    }
  };
  
  // Need to await so that I can call context.log before function returns
  await twin.update(propertyPatch)
    .catch(updateTwinErr => {
      if (updateTwinErr) {
        context.res = {
          status: 400,
          body: `Could not update device twin for device with Id ${deviceId}`
        };
        context.log(updateTwinErr);
      }
  });
};

export default httpTrigger;

At this point we should be able to trigger this Azure Function to update our device's status.

Note: this obviously has not been secured in any way. Clients generally should not have direct access like this to your IoT Hub. One possible security improvement would be to create a proxy that has access to a secret it can forward to this Azure Function, and users could authenticate against the proxy and use it instead. This will be the subject of a future post.

After hitting F5 to start debugging our functions, we can POST the following:

Execute that, visit the device twin in the Azure portal, and we can see that our device's desired properties - and reported properties - have been updated:

"properties": {
    "desired": {
      "status": "on",
      "$metadata": {
        "$lastUpdated": "2020-02-14T20:18:53.4911471Z",
        "$lastUpdatedVersion": 71,
        "status": {
          "$lastUpdated": "2020-02-14T20:18:53.4911471Z",
          "$lastUpdatedVersion": 71
        }
      },
      "$version": 71
    },
    "reported": {
      "status": "on",
      "$metadata": {
        "$lastUpdated": "2020-02-14T20:18:53.6069387Z",
        "status": {
          "$lastUpdated": "2020-02-14T20:18:53.6069387Z"
        }
      },
      "$version": 72
    }

Coding our client webpage

We are going to code a very simple webpage that will print out telemetry messages from a device with the id of test-device, the same one used in a previous post. We will also change its state as we did before with a web request.

I'll include the source of the webpage in its entirety at the end of this post until I get everything moved over to Github.

Handling incoming device-to-cloud message

This hasn't changed since the previous post where we set up our SignalR Service. We receive the message, stringify it and then render it onto the page:

function handleMessage(message) {
  document.querySelector("#log").innerHTML = `<div>${JSON.stringify(
    message
  )}</div>`;
}

Sending cloud-to-device message

Instead of broadcasting a message to a SignalR Service group, we are going to instead send a message via our new cloudToDevice Azure Function.

function sendMessage() {
  const newStatus = document.querySelector("#isOn").value;

  const payload = { status: newStatus };

  axios.post(`${apiBaseUrl}/api/cloudToDevice?deviceId=${DEVICE_ID}`, payload);
}

Have I mentioned I am not a designer?

Here is the rudimentary UI I have built that allows a user to subscribe to test-device's telemetry stream and also set its status:

Once I click the checkbox to subscribe, telemetry will start rendering in real-time on the page:

If I set the a status in my dropdown and hit the Send button, my Azure Function will forward the message to my IoT Hub.

To re-iterate, this is not secure and you shouldn't provide your client direct access to your IoT Hub like this.

As you hit the send button, you should see the test-device device twin update its desired and reported properties:

{
  "deviceId": "test-device",
  "tags": {
    "kind": "outlet"
  },
  "properties": {
    "desired": {
      "status": "on",
      ...
    },
    "reported": {
      "status": "on",
      ...
 }

Wrapping up

We now have a simple but super cool platform that lets us provision devices, publish telemetry, receive updates in real-time, and manage our devices from our computer or phone.

In a future post I will go through the exercise of deploying this code into Azure so that it will be always on and available for use. I'll also upload all the relevant code to Github. Until then, here is the full source of the client webpage:

<html style="font-size: 20px;padding: 20px;">
  <body>
    <div style="float: left; margin-right: 80px">
      <div>
        <input type="checkbox" id="subscribe" name="subscribe" >
        <label for="subscribe">Subscribe to test-device telemetry</label>
      </div>
    </div>
    <div style="float: left;margin-bottom: 50px; border-left: 1px solid #ccc; padding-left: 20px;">
      <div>
        <label for="isOn">Set device status</label><br />
        <select id="isOn">
          <option value="on">On</option>
          <option value="off">Off</option>
        </select> 
        <button id="send">Send</button>
      </div>
    </div>
    <hr style="clear:both;" />
    <h3>Telemetry data</h3>
    <div id="log" style="margin-top: 50px">No telemetry received</div>
    <script src="https://cdn.jsdelivr.net/npm/@aspnet/signalr@1.1.2/dist/browser/signalr.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/axios@0.18.0/dist/axios.min.js"></script>
    <script>
      const username = new URLSearchParams(window.location.search).get("username");
      var apiBaseUrl = "http://localhost:7071";
      const deviceId = "test-device";

      function changeGroup(event) {
        if(event.target.checked) {
          axios.post(
            `${apiBaseUrl}/api/joinGroup?userId=${username}&groupName=${deviceId}`
          );
        }
        else {
          axios.post(
            `${apiBaseUrl}/api/leaveGroup?userId=${username}&groupName=${deviceId}`
          );
        }
      }

      function sendMessage() {
        const newStatus = document.querySelector("#isOn").value;

        const payload = { status: newStatus };

        axios.post(`${apiBaseUrl}/api/cloudToDevice?deviceId=${deviceId}`, payload);
      }

      function handleMessage(message) {
        document.querySelector("#log").innerHTML = `<div>${JSON.stringify(
          message
        )}</div>`;
      }

      document.querySelector("#subscribe").onclick = changeGroup;
      document.querySelector("#send").onclick = sendMessage;

      var connection = new signalR.HubConnectionBuilder()
        .withUrl(`${apiBaseUrl}/api/${username}`)
        .configureLogging(signalR.LogLevel.Information)
        .build();
      
      connection.on("handleMessage", handleMessage);
      
      connection
        .start()
        .catch(console.error);
    </script>
  </body>
</html>

Tensorflow has been ported over as a Javascript library that is compatible in both browser and Node.js runtimes. I got image classification and object detection up running with a few hurdles I'll call out in this post which will hopefully get smoothed out with time.

Image classification

Image classification is where we provide Tensorflow with an image, and it will indicate what class it believes the object represents.

Object detection

Object detection is where we provide Tensorflow with an image with possibly multiple objects, and it will indicate whether an object of a particular class has been detected. Some machine learning models will also provide a bounding box to show where each object is in the image.

Wait, what's a model?

A machine learning model is a set of assumptions used to make predictions about data. The models I have seen in my limited experience are trained by providing them large amounts of data and then having humans tell them what that data means. This is an example of supervised learning, where the model is trained on data where both the inputs and outputs are supplied.

Unsupervised learning involves providing inputs but no outputs, the model has to identify patterns on its own. I have no idea how this works :)

Pre-existing models

What's really cool about this concept of a model is that once they have been trained, they can be distributed to run on other Tensorflow instances. For instance, Google has created a detection model zoo where anyone can grab a copy of a model and run them without going through the labourious effort to train one themselves.

Those models are compatible with Tensorflow, which is written in Python, but if we want to stick with Javascript, there have been some models ported over to Tensorflow.js.

Setting up

• a Raspberry Pi 3 with at least Rasbian Buster updated and upgraded
• a Raspberry Pi camera
• Node.js v10 - I had issues with Node v12, and didn't attempt a previous version of Node.js

Create your project

On your Raspberry Pi, create a new folder called camera-test. cd into it and run npm init and use all the defaults.

Use the following for your package.json and run npm install:

{
  "name": "camera-test",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "ts-node index.ts --skipLibCheck true"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^13.7.1",
    "ts-node": "^8.6.2",
    "typescript": "^3.7.5"
  },
  "dependencies": {
    "@tensorflow-models/coco-ssd": "^2.0.1",
    "@tensorflow-models/mobilenet": "^2.0.4",
    "@tensorflow/tfjs-node": "1.2.11"
  }
}

Note the pinned version for @tensorflow/tfjs-node - there is a more recent version, but on the Raspberry Pi I wasn't able successfully build a binding with it, a task we'll get to shortly.

After you have installed the above packages, we need to manually build the Tensorflow Node.js binding. This is a Raspberry Pi-only step, I'm unsure why it is necessary.

npm rebuild @tensorflow/tfjs-node --build-from-source

Finally, if you're using Typescript like I am, you'll need to adjust your tsconfig.json to include the skipLibCheck: true compiler option.

Predictive analysis script

I'm going to post the entire script to capture a still image from my Rasperry Pi camera, and then have it processed by both an image classifier model and an object detection model.

import * as tf from "@tensorflow/tfjs-node";
import * as fs from "fs";
import * as mobilenet from "@tensorflow-models/mobilenet";
import * as cocoSsd from "@tensorflow-models/coco-ssd";
import { spawn } from "child_process";

var filename = "./capture.jpg";
// Set camera arguments
var args = [ "-hf", "-vf", "-w", "2592", "-h","1944", "-o", filename, "-t", "1" ];

var spawned = spawn("raspistill", args);

spawned.on("exit", function() {
  fs.readFile(filename, async (err, data) => {
    if (err) {
      console.error(err);
    }

    const imgTensor = tf.node.decodeJpeg(data);

    const mobileNetmodel = await mobilenet.load();
    const mobilenetPredictions = await mobileNetmodel.classify(imgTensor);

    console.log("Mobilenet predictions: ");
    console.log(mobilenetPredictions);

    const cocoModel = await cocoSsd.load();
    const cocoPredictions = await cocoModel.detect(imgTensor);

    console.log("Coco predictions: ");
    console.log(cocoPredictions);
  });
});

I didn't have much success with the mobilenet model - it once accused me of being a sofa. Now, I believe the Javascript port is not the most recent version, and also this mobile-optimized library sacrifices accuracy for the sake of speed. Things may improve with time.

However, I was pretty pleased with how well the coco-ssd model ran. It detected various members of my family and pets in images and applied a class and bounding box where the object was detected.

For the above photo, coco-ssd produced the following:

Coco predictions:
[ { bbox:
     [ 852.9707651138306,
       449.7543740272522,
       953.0751829147339,
       1483.4483785629272 ],
    class: 'cat',
    score: 0.9699275493621826 },
  { bbox:
     [ 32.730048179626465,
       286.1092700958252,
       1323.1229524612427,
       1671.2676229476929 ],
    class: 'person',
    score: 0.7677765607833862 } ]

Without a whole lot of code required, my little Raspberry Pi can now scan images and identify detections with a classification, bounding box and confidence scores. When I eventually get around to building a wildlife camera, I'm pretty much there!

I've played with SignalR off and on since it was released, and in the course of building apps with it, it became apparent that I would end up writing near-identical functions over and over. Users need to connect. Users need to enrol in groups. Users need to send messages.

What's cool about SignalR Service is there is a serverless option that means next to no setup necessary, no infrastructure to worry about, and the repetitive back-end code I used to have to write has been replaced with terse Azure Functions. Azure Functions are another serverless PAAS offering that lets you run code without worrying about infrastructure. You can write them in .Net, Python, Java, Javascript - or in my case - Typescript!

Pre-requisites

• VS Code - Microsoft's lightweight IDE
• Azure Functions for Visual Studio Code Extension - lets you create, manage and deploy Azure Functions from within Visual Code
• Azure Functions Core Tools - npm install -g azure-functions-core-tools
• An Azure subscription

Create the SignalrR Service resource

Bring up the Azure Portal and find the SignalR Service. Specify your subscription and resource group, and specify the Free pricing tier and Serverless option for  ServiceMode.

The Free tier is more than enough for my needs. It provides a single unit, which allows for 20 concurrent connections and 20,000 messages. Note that I will not be connecting IoT devices to SignalR Service, only my clients, which will only be a handful. (I'll go into detail about the end-to-end flow of messages from devices to clients via SignalR in a future post.)

Once the deployment is complete, take note of the keys and connection strings that have been generated, our Azure Functions will need them.

Create your first Azure Function in VS Code

After you have installed the Azure Functions extension mentioned above, a new Azure menu item in the sidenav will appear. Click on it, and then click on the Create New Project button at the top:

Select the folder to create the new project in. For my language choice, I've selected Typescript. Choose to make a HTTP Trigger function.

Name it negotiate - this name is important as it will be used for an endpoint name that SignalR Service will consume based on convention.

For Authorization Level, choose Anonymous

Once that's done, a new Azure Function will be added to the project with boilerplate code. The project view shows a high-level overview of your functions and their bindings which we'll discuss shortly.

Click on the Explorer button in the sidenav and you can see a number of things have been created on disk.

Manage settings with local.settings.json

While developing locally, settings will be read in from local.settings.json We'll need to include our SignalR Service connection string we captured from the portal, and we'll also need to configure CORS as our webpage will end up in a domain different than our Azure Functions domain.

{
  "IsEncrypted": false,
  "Values": {
    "AzureSignalRConnectionString": "<ENTER CONN STRING HERE>",
    "FUNCTIONS_WORKER_RUNTIME": "node",
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "http://localhost:8080",
    "CORSCredentials": true
  }
}

negotiate Azure Function

The purpose of this function is to negotiate a token from the SignalR Service and provide it to the client. The client will then supply the token to SignalR Service for authentication.

Edit negotiate's function.json

Open /negotiate/function.json for editing. This file supplies configuration details at the function level. Looking at the boilerplate, you can see that a couple bindings have been included that are standard for a HTTP trigger.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ],
  "scriptFile": "../dist/negotiate/index.js"
}

Bindings are resources that you can declaratively attach to your functions. Input bindings are triggers that invoke the function, while output bindings are where the Azure Functions emit their result.

Bindings are optional, there's nothing stopping you from writing imperative code inside your function. But if you have a binding available to you, they can be an excellent choice to reduce the amount of code you need to write. We'll see how the repetitive back-end code I used to have to write has been minimized by leveraging existing bindings.

We are going to make a couple changes to this file. We are going to alter the input binding's route so we can supply a userId to SignalR service, which is a mandatory piece of identity we need to supply if we want to enrol our users into groups.

    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      ...
      "route": "{userId}/negotiate"
    },
    ```

We will now add an additional input binding so that we can accept real-time communication from our SignalR Service hub called chat:

	{
      "type": "signalRConnectionInfo",
      "name": "connectionInfo",
      "hubName": "chat",
      "direction": "in",
      "userId": "{userId}"
    }

At the end your function.json should look like this:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "post"
      ],
      "route": "{userId}/negotiate"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "signalRConnectionInfo",
      "name": "connectionInfo",
      "hubName": "chat",
      "direction": "in",
      "userId": "{userId}"
    }
  ],
  "scriptFile": "../dist/negotiate/index.js"
}

Edit negotiate's index.ts

This is where the declarative binding really starts to shine. Delete the contents of /negotiate/index.ts and replace it with the following:

import { AzureFunction, Context, HttpRequest } from "@azure/functions"

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest, connectionInfo: any): Promise<void> {
    context.res.json(connectionInfo);
};

export default httpTrigger;

This one liner negotiates authentication tokens from SignalR Server and provides them to our clients so they can authenticate. Easy!

joinGroup Azure Function

SignalR has the concept of groups, which allows for messaging to be targeted to a subset of connected users. They aren't strictly necessary, but for my IoT Home Automation platform, they are useful so that I can direct data from my devices to only the clients that wish to observe that data by joining a group with the name of the device's ID.

Go ahead and create another HTTP Trigger Azure Function like before, but this time call it joinGroup.

Edit joinGroup's function.json

Again, we are going to leverage a pre-existing binding that exposes SignalR group management actions. We are going to add the signalRGroupActions binding to the bottom of the file, which should now look like:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "signalR",
      "name": "signalRGroupActions",
      "hubName": "chat",
      "direction": "out"
    }
  ],
  "scriptFile": "../dist/joinGroup/index.js"
}

Edit joinGroup's index.ts

Again, we'll leverage our declarative binding to enrol a user into a group. We will also accept the group's name as a querystring parameter. If the group doesn't exist, the group will be created.

import { AzureFunction, Context, HttpRequest } from "@azure/functions";

const httpTrigger: AzureFunction = async function(
  context: Context,
  req: HttpRequest
): Promise<void> {
  context.bindings.signalRGroupActions = [
    {
      userId: req.query.userId,
      groupName: req.query.groupName,
      action: "add"
    }
  ];
};

export default httpTrigger;

leaveGroup Azure Function

This function is nearly identical to the joinGroup function so I won't dive into it. The function.json is the same, but there is a slight change to the index.ts to indicate a different group action:

import { AzureFunction, Context, HttpRequest } from "@azure/functions";

const httpTrigger: AzureFunction = async function(
  context: Context,
  req: HttpRequest
): Promise<void> {
  context.bindings.signalRGroupActions = [
    {
      userId: req.query.userId,
      groupName: req.query.groupName,
      action: "remove"
    }
  ];
};

export default httpTrigger;

sendToGroup Azure Function

The final function we need will send messages to members of a specific group. Create another HTTP Trigger function like before.

Edit sendToGroup's function.json

We'll add the signalRMessages binding to the function.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "signalR",
      "name": "signalRMessages",
      "hubName": "chat",
      "direction": "out"
    }
  ],
  "scriptFile": "../dist/sendToGroup/index.js"
}

Edit sendToGroup's index.ts

We will supply the binding with three properties:

• groupName - the name of the group we want to send a message to
• target - this is the name of the function we want to invoke on our client. We'll go into this later where we code the handleMessage using the SignalR client library.
• arguments - this represents the arguments we pass into the target function we specified. We're going to pass our request body in.

import { AzureFunction, Context, HttpRequest } from "@azure/functions";

const httpTrigger: AzureFunction = async function(
  context: Context,
  req: HttpRequest
): Promise<void> {
  context.bindings.signalRMessages = [
    {
      // message will only be sent to this group
      groupName: req.query.groupName,
      target: "handleMessage",
      arguments: [req.body]
    }
  ];
};

export default httpTrigger;

If you want to send a message to a single user, remove the groupName property and replace it with "userId": "myUserId"

Running your Azure Functions locally

Now that our functions have been coded, hit F5 to start debugging. This will execute npm install, then npm build, followed by func host start

If everything worked. you should see a message indicating your application has started, and a list of your functions with their URLs.

Building our client web page

To test everything, we'll create a rudimentary webpage (I'll include full source at the bottom of this page until I get the code copied over to Github). Users will click checkboxes to join and leave a couple of groups - the Super Group and the Awesome Group. Users will also be able to send messages to those groups.

We'll start with this markup:

<div style="float: left; margin-right: 80px">
    <div>
        <input type="checkbox" id="superGroup" name="superGroup" >
        <label for="superGroup">Join super group</label>
    </div>
    <div>
        <input type="checkbox" id="awesomeGroup" name="awesomeGroup" >
        <label for="awesomeGroup">Join awesome group</label>
    </div>
</div>
<div style="float: left">
    <div>
        <label for="superGroupText">Send message to super group</label><br />
        <input type="text" id="superGroupText" name="superGroupText" />
        <button id="sendSuperMessage">Send</button>
    </div>
    <br />
    <div>
        <label for="awesomeGroupText">Send message to awesome group</label><br />
        <input type="text" id="awesomeGroupText" name="awesomeGroupText" />
        <button id="sendAwesomeMessage">Send</button> 
    </div>
</div>
<br style="clear:both" />
<div id="log" style="margin-top: 50px" />

We are now going to create some functions that will consume the endpoints our Azure Functions have exposed. We'll start with the functions to join and leave groups. I'll use Axios to make this is a little easier on myself:

const username = new URLSearchParams(window.location.search).get("username");
var apiBaseUrl = "http://localhost:7071";
      
function joinGroup(groupName) {
    axios.post(
        `${apiBaseUrl}/api/joinGroup?userId=${username}&groupName=${groupName}`
    );
}

function leaveGroup(groupName) {
    axios.post(
        `${apiBaseUrl}/api/leaveGroup?userId=${username}&groupName=${groupName}`
    );
}

To send a message, we'll capture the text in an input and include it in the payload to our endpoint:

function sendMessageToGroup(groupName, buttonId) {
    const text = document.querySelector(buttonId).value;

    axios
        .post(`${apiBaseUrl}/api/sendToGroup?&groupName=${groupName}`, {
        sender: username,
        group: groupName,
        text: text
    })
}

Remember when we registered the handleMessage target in our sendToGroup Azure Function? We're now going to code its implementation to render the message onto the screen.

function handleMessage(message) {
    document.querySelector("#log").innerHTML = `<div>${JSON.stringify(
        message
    )}</div>`;
}

Finally, we need to build our SignalR connection, register the handler for the handleMessage target, and start it.

var connection = new signalR.HubConnectionBuilder()
    .withUrl(`${apiBaseUrl}/api/${username}`)
    .configureLogging(signalR.LogLevel.Information)
    .build();

connection.on("handleMessage", handleMessage);

connection
    .start()
    .catch(console.error);

The page needs to be served from a webserver, CORS will fail for a page served off disk. http-server can be used for this, just ensure it serves at http://localhost:8080 as that is the URL we specified in local.settings.json in our CORS configuration.

Once your server is up and running, browse to your page ensuring you include a username as a querystring parameter:

http://localhost:8080/index.html?username=Jack

If you open Devtools, you should see a happy message in your console indicating a successful connection.

[2020-02-11T17:43:24.224Z] Information: WebSocket connected to wss://serverless-demo.service.signalr.net/client/?hub=chat&id=C_tHxxx

If you open your network tab and click on WS, you can select your websocket connection to see the frames being passed back and forth. In the capture below you can see {type: 6} being ferried around - it's a keepalive message. In the event that the browser doesn't send notification of a disconnection - say if there is a power failure - then the keepalive message won't be returned to SignalR indicating the connection is no longer valid.

Open a second browser window, and open your page but with a different username.

http://localhost:8080/index.html?username=Jill

You should now be able to join and leave groups, and send messages between the two users!

As promised, here is the full source of the webpage.

<html style="font-size: 20px">
  <body>
    <div style="float: left; margin-right: 80px">
      <div>
        <input type="checkbox" id="superGroup" name="superGroup" >
        <label for="superGroup">Join super group</label>
      </div>
      <div>
        <input type="checkbox" id="awesomeGroup" name="awesomeGroup" >
        <label for="awesomeGroup">Join awesome group</label>
      </div>
    </div>
    <div style="float: left">
      <div>
        <label for="superGroupText">Send message to super group</label><br />
        <input type="text" id="superGroupText" name="superGroupText" />
        <button id="sendSuperMessage">Send</button>
      </div>
      <br />
      <div>
        <label for="awesomeGroupText">Send message to awesome group</label><br />
        <input type="text" id="awesomeGroupText" name="awesomeGroupText" />
        <button id="sendAwesomeMessage">Send</button> 
      </div>
    </div>
    <br style="clear:both" />
    <div id="log" style="margin-top: 50px" />
    <script src="https://cdn.jsdelivr.net/npm/@aspnet/signalr@1.1.2/dist/browser/signalr.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/axios@0.18.0/dist/axios.min.js"></script>
    <script>
      const username = new URLSearchParams(window.location.search).get("username");
      var apiBaseUrl = "http://localhost:7071";
      
      function handleGroupChange(event, groupName) {
        if (event.target.checked) {
          joinGroup(groupName);
        }        
        else {
          leaveGroup(groupName);
        }
      }

      function joinGroup(groupName) {
        axios.post(
          `${apiBaseUrl}/api/joinGroup?userId=${username}&groupName=${groupName}`
        );
      }

      function leaveGroup(groupName) {
        axios.post(
          `${apiBaseUrl}/api/leaveGroup?userId=${username}&groupName=${groupName}`
        );
      }

      function sendMessageToGroup(groupName, buttonId) {
        const text = document.querySelector(buttonId).value;

        axios
          .post(`${apiBaseUrl}/api/sendToGroup?&groupName=${groupName}`, {
            sender: username,
            group: groupName,
            text: text
          })
      }

      document.querySelector("#superGroup").onclick = (e) => handleGroupChange(e, "superGroup");
      document.querySelector("#awesomeGroup").onclick = (e) => handleGroupChange(e, "awesomeGroup");

      document.querySelector("#sendSuperMessage").onclick = () => sendMessageToGroup("superGroup", "#superGroupText");
      document.querySelector("#sendAwesomeMessage").onclick = () => sendMessageToGroup("awesomeGroup", "#awesomeGroupText");

      function handleMessage(message) {
        document.querySelector("#log").innerHTML = `<div>${JSON.stringify(
          message
        )}</div>`;
      }
            
      var connection = new signalR.HubConnectionBuilder()
        .withUrl(`${apiBaseUrl}/api/${username}`)
        .configureLogging(signalR.LogLevel.Information)
        .build();
      
      connection.on("handleMessage", handleMessage);
      
      connection
        .start()
        .catch(console.error);
    </script>
  </body>
</html>

For our purpose, we will use the transistor to control a higher-voltage circuit. The Raspberry Pi can supply 3.3 volts, which is often not enough to drive the device you are attempting to power. To make things work we will need a few things.

Power supply unit

To supply a higher voltage, we'll use a common power supply unit like this one, which outputs at 12V:

Note that I cut off the normal plug and attached a terminal I got from this set. I won't write about how you use a crimping tool like this one because there are plenty of great Youtube videos that would do better justice to the subject matter, and also because I'm not very good at it :)

TIP120 transistor

This is a cheap and common component you can get from any electronics store.

The pins connect to the three parts of the component:

• the base which activates the transistor (left lead in this model)
• the collector which is the positive external lead (center lead in this model)
• the emitter which is the negative external lead (right lead in this model)

To drive a device, we connect the power supply unit and the device into a circuit with this transistor mediating power flow. When we supply current to the base lead from our Raspberry Pi, the transistor will activate and close its circuit which will start supplying the device with power from our power supply unit.

Using pulse width modulation (PWM) via the Raspberry Pi's GPIO18 pin, you can pulse the base lead intermittently, creating duty cycles which supplies and cuts power at desired intervals. This is how you would control the intensity of a fan.

Creating the circuit

To create this circuit you will need:

• 1K ohm resistor
• 1 N4001 diode
• TIP120 transistor
• power supply unit
• a fan or some other device to power
• Raspberry Pi

With those components in hand, the circuit will look like this:

If you wish to use PWM, connect GPIO18 to the base lead of the transistor, which is the leftmost one.

Be sure to include a diode oriented in the direction indicated in the diagram, which ensures current will run in one direction. Without it, a higher current than your Raspberry Pi can handle could run through your board and ruin it.

If you want to turn the current completely on or off, it's just a matter of writing high or not to the pin. To be a bit more interesting, I'll show some code that leverages PWM to control the intensity of a fan. I'll be using Johnny-Five, a great library that let's us create robots and smart devices with Javascript.

import PiIO from 'pi-io';
import five from 'johnny-five';

const board = new five.Board({
  io: new PiIO()
});

board.on("ready", function() {
  board.pinMode('GPIO18', five.Pin.PWM);
  
  // analogWrite accepts an int between 0-255 which controls the 
  // duty cycle supplying power to your device
  board.analogWrite('GPIO18', 1 * 255); // 100% of full power
  
  // after 5 seconds, reduce to 25%
  setTimeout(() => {
    board.analogWrite('GPIO18', 0.25 * 255); // 25% of full power
  }, 5000);
});

Now that I can control a fan, I am able to control the temperature of my kamodo grill whose temperature is controlled by the amount of air flow through its bottom vent. I can read a bbq probe that is dangling inside my dome, and based on whether the temperature is above or below a threshold I set, the fan will turn on or off to maintain my desired temperature.

You can see below there is a squirrel cage blower that I've connected to my bottom vent via some tubing that is food safe to use at high temperatures.

And yes, that pulled pork was totally delicious.

The IoT Hub ingests message at massive scale, but has a lot of other really cool features that make setting up my platform really easy:

• device registration and management
• remote control
• monitoring
• security

Setting up your IoT Hub in the Azure portal

There are a couple ways to provision an IoT Hub, but we'll use the Azure portal. First, find the IoT Hub resource in the portal and click Create.

For the basics, you'll need to fill out your subscription, resource group, region and IoT Hub name. Your resource group and IoT Hub name must be unique to your region.

Next, select Size and Scale to set your hub's size:

What's really nice about the IoT Hub is there is a free tier! I already have a Hub, so you can see above the error indicating I can't have more than one. This is a fully functional hub, but with the disadvantage of a small message per day allowance of 8000 messages. If you are going to exceed this allowance, you'll need to bump up your tier to Basic or Standard. The big downside to the Basic tier is that you cannot send messages to your device, which is a showstopper for me.

Leave the Device-to-cloud partitions to 2 (you can't change it on the free tier anyway). More partitions give you flexibility to scale out ingestion during times of heavier load. For a home automation platform, 2 is more than enough.

Review your changes, click create, and wait for your hub to be deployed:

Provisioning a device in the IoT Hub registry

Once your hub has been created, we need to provision a new device in the hub registry in order to generate keys our physical device will use to send messages to the hub.

In an enterprise scenario, device provisioning is a complex operation, with certificates burned onto device silicone and managed with something like the Azure Device Provisioning Service. For our scenario, manually provisioning a few home automation devices won't be particularly cumbersome.

Click IoT Devices in the navigation menu, and we'll be presented with an empty list of devices. Add one by clicking New:

Assign a Device ID - it can be completely arbitrary what you call it, I'm going to call mine test-device, leave the Authentication Type as Symmetric Key, and Auto-generate its keys:

Once created, it will show up in our device list:

Drill into it and we access its keys, connection strings, manage whether it is allowed to connect to the IoT Hub and more. Note there are two keys so that if we think a key has been compromised, we can rotate the keys so as to invalidate the compromised one.

We'll come back after we have connected our device to check out some of the other functionality. For the moment, take note of your primary connection string as you'll need it in the next section.

Connecting your device to the IoT Hub

For the purpose of your device, it can be a Raspberry Pi, an Arduino, or you can use your plain ol' laptop. Anything that runs Node will work.

Create a new Node project with npm init and install these dependencies:

npm install azure-iot-device azure-iot-device-mqtt --save

Next, create an index.js file and create your IoT Hub client using your settings from when you created your hub:

import DeviceSDK from "azure-iot-device";
import Transport from "azure-iot-device-mqtt";

// UPDATE CONN_STRING WITH YOUR CONNECTION STRING
const CONN_STRING =
  "HostName=iot-hub-chardie.azure-devices.net;DeviceId=test-device;SharedAccessKey=XXXXXXXXXXXX";
const client = DeviceSDK.Client.fromConnectionString(
  CONN_STRING,
  Transport.Mqtt
);

client.open(err => {
  if (err) {
    console.err(err.toString());
    process.exit(-1);
  }

  console.log("Connected to IoT Hub!");
  // MORE AWESOME CODE TO GO HERE!
});

Note we are using Mqtt as our protocol, which is extremely lightweight with low bandwidth requirements, but there are also Https and Amqp protocols available with their own pros and cons.

Run the script and make sure Connected to IoT Hub! is logged to the console.

If we go back to the Azure portal and drill into our device, we can select Device Twin - which is a virtual representation of our device - in order to see various properties and metadata. We can see that our device's connection state is connected:

{
  "deviceId": "test-device",
  ...
  "connectionState": "Connected",

Now that our device is connected, we can start communicating between our device and the IoT Hub.

Device-to-cloud communication

There are two ways for your device to communicate with your IoT Hub:

• Telemetry event messages
• Device Twin Reported Properties

Telemetry event messages

The most common IoT communication scenario is a device capturing some telemetry data and pushing it to an ingestion service. For simplicity's sake, we're going to simulate a temperature being recorded and publish it to our IoT Hub.

When our connection opens, we will set an interval of 5 seconds where we will generate a random temperature reading and push it to Azure.

client.open(err => {
  ...
  const sendTelemetry = () => {
    // Generate a random int between 0 - 4 to represent a temperature
    const temperature = Math.floor(Math.random() * Math.floor(5));

    var message = new DeviceSDK.Message(
      // SDK doesn't take care of serialization, we must stringify ourselves
      JSON.stringify({
        temperature
      })
    );

    client.sendEvent(message, function(err) {
      if (err) {
        console.error(err.toString());
        process.exit(-1);
      }
      console.log(`Message sent: ${message.data.toString()}`);
    });
  };

  setInterval(sendTelemetry, 5000);

Our console should start logging messages like:

Message sent: {"temperature":1}
Message sent: {"temperature":0}
Message sent: {"temperature":4}

At this point, if we flip over to the Azure portal and bring up the IoT Hub Overview window, we can see our Device to cloud messages being captured:

Device Twin Reported Properties

Note that this method requires the Standard (or Free) tier of IoT Hub.

This method of communication is typically used to communicate some status of the device so that it can be captured in its device twin, which is its virtual representation in IoT Hub. Device twins can be queried to provide rich detail about the status your physical devices.

To update a reported property, retrieve the device twin and make an assignment like this:

client.open(err => {
  ...

  client.getTwin((twinErr, twin) => {
    if (twinErr) {
      console.error("Could not retrieve twin");
      process.exit(-1);
    }
      
    const propertiesPatch = {
        batteryLife: 50
    }

    twin.properties.reported.update(propertiesPatch, function(err) {
      if (err) {
        throw err;
      }
      console.log("Reported battery life"));
    });
  });
});

Note batteryLife is completely arbitrary, your property could be named anything.

Open the Azure portal, drill into your IoT Device and click on Device Twin:

You should see its reported properties now includes batteryLife:

Cloud-to-device communication

There three ways to control your IoT device:

• Cloud-to-device messages
• Direct methods
• Device Twin Desired Properties

Note that all three methods require the Standard (or Free) tier of IoT Hub. Each method has different features which are detailed in Microsoft's documentation, but in brief:

Cloud-to-device message - These are unidirectional messages sent without the expectation of a return value. For the AMQP and HTTPS protocols, the IoT Hub can be made aware the message was processed, but there is no expectation there should something returned which should be acted upon. Messages are stored on the IoT Hub for 48 hours, and will be delivered once the device connects.

Direct methods - A direct method is an immediate invocation of a function that exists on the device where the function can return a value. This makes the communication fully bidirectional. If the device is not connected, the direct method will fail to invoke and will not retry.

Device Twin Desired Properties - These are properties on the device's digital twin that will be communicated when the device connects to the IoT Hub, there is no expiration of this message. These are intended to put the device into a desired state.

Cloud-to-device message

Receiving a message is just a matter of registering a handler for the device client's message event:

client.open(function (err) {
  ...
  client.on("message", msg => {
    console.log(`Received message: ${msg.data.toString()}`);
  });

While your Node app is running, bring up the Azure portal again, browse to your IoT Device and click the Message to Device link:

We'll add "Hi from Azure!" to our message body and click Send Message:

After you click Send Message, your Node app should log out:

Received message: Hi from Azure!

MQTT has no concept of completing a message, but AMQP and HTTPS transports do, and this will inform IoT Hub that the message has been processed in case you need to inform some retry or compensation workflow:

client.on('message', function (msg) {  
  ...
  client.complete(msg, function (err) {
    if (err) {
        client.error(`Could not complete message ${err.toString()}`);
    } else {
        console.log('message has completed');
    }
  });
})

Direct methods

Similar to handling cloud-to-device messages, setting up a direct method involves creating a handler with the client's onDeviceMethod method. The following sample simulates receipt of a direct method message which invokes the device's setFanStatus method. The request payload is interrogated for the status value to apply to the fan, turns the fan on or off, and then sends the response to the IoT to confirm the fan is now in the desired state.

client.open(function (err) { 
  ...
  const setFanStatus = (request, response) => {
    console.log(`Received: ${JSON.stringify(request.payload)}`);

    if (request.payload.status === "on") {
      fan.turnOn();
    } else if (request.payload.status === "off") {
      fan.turnOff();
    }

    const fanPayload = {
      currentStatus: fan.status
    };

    response.send(200, fanPayload, respErr => {
      if (respErr) {
        console.error(respErr.ToString);
        process.exit(-1);
      }
      console.log("response to setFanStatus sent");
    });
  };

  client.onDeviceMethod("setFanStatus", setFanStatus);
}

With your Node app running, open the Azure portal and drill into your IoT Device and click Direct Method:

In the Direct Method window, assign "setFanStatus` to Method Name, and add the following to the Payload:

{
  status: "on"
}

After clicking Invoke Method, you should receive a Result indicating the current status of the fan is on:

Going back to your Node app, the console should have logged confirmation it received a message and that it responded with a confirmation:

Received: {"status":"on"}
response to setFanStatus sent

Device Twin Desired Properties

Desired properties put a device into a desired state. In this example, we'll push down a message to alter the device's telemetry data push interval.

Using the device client, we request the device twin from IoT Hub, and when it is retrieved, we will set up a handler to handle change events to our custom desired property. Note that the handler will be invoked not only when the property has changed, but also when your application starts up with the current value of the desired property.

client.open(err => {
  ...

  client.getTwin((twinErr, twin) => {
    if (twinErr) {
      console.error("Could not retrieve twin");
      process.exit(-1);
    }

    twin.on("properties.desired.pushInterval", pushInteval => {
      console.log(`Received update to pushInterval: ${pushInteval}`);
    });
  });
});

In the above sample, we begin to observe a pushInterval property. This is something I came up with, it could be named anything. When the value is changed in device twin, the change will be raised on the device where it can be handled however desired.

With your Node app running, open the Azure portal, drill into your Iot Device and click on Device Twin:

You will be presented with a JSON document, which is the virtual representation of your device. Under properties.desired, add a new property called pushInterval and give it a value of 10:

Click Save, and the change will be raised if your device is presently connected, or will be raised as soon as your device connects to the IoT Hub.

You can observe changes made to pushInterval in the desired properties' $metadata property.

Flip back to your Node app, and the desired property update for pushInterval should be logged out:

Received update to pushInterval: 10

This is the fastest and simplest way to control power - no soldering or special tools required. Grab a couple jumper cables and screw them into the pin connector (the green box in the image above) and you're pretty much good to go.

Connect your board and write high to the data pin to flip the relay and start supplying power to two outlets that are normally off. There is also another outlet that is normally on, but will be unpowered while the data pin is high. Finally there is an outlet that is always on, which is convenient if you need a place to plug your board into.

This is a pretty rugged device, and it handles a higher load than the RF outlets, which will burn out if you connect an appliance over 1200W.

A good sample of tutorials can be found on Digital Loggers site.

Creating your backup

When creating a copy of your files, it's best to stop your docker container during the process so your SQLite database doesn't corrupt if a copy operation is initiated while Ghost attempts to write to the database.

Note if you use MySQL or MariaDB as your Ghost database, you should investigate how to create a backup using their CLI or APIs.

The following bash script does three things:

1) it stops the docker container named "blog"

2) it creates a compressed tarball archive of all our Ghost files found at volume1/docker/blog and deposits them at /volume1/Share/blog-backup

3) it re-starts the docker container

#!/bin/sh

docker stop blog
sudo tar -czvf /volume1/Share/blog-backup/blog-backup.tar.gz /volume1/docker/blog
docker start blog

Place the above script at /volume1/public/blog-backup.sh

Scheduling the backup job

Synlogy includes a Task Scheduler which, like cron, will run tasks based on a schedule you setup.

Open up Control Panel -> Task Scheduler and enter "Blog backup" as the task name, and leave root for the owner (I'm sure I'm violating some common sense security principle here)

I set up my task to run every morning at 4 a.m.

Finally I indicate the location of the script file I want to execute: /volume1/public/blog-backup.sh

Once your script executes, you should see a tarball archive in your backup diretory:

ls -la /volume1/Share/blog-backup/

Moving your backup to Google Drive

Syncing files with Google Drive - and a number of other providers - is facilitated by Cloud Sync, an official Synology package. Download it from the Package Center and it will step you through setting up a sync:

You will need to authorize Cloud Sync to access your Google Drive. First sign in with the account linked to your drive:

And then grant permission for Cloud Sync to use it:

Synology then steps in to link everything together:

Record the appropriate local and remote paths between your NAS and Google Drive:

I haven't bothered with "Schedule settings", by default it will copy things over in real time, which is fine for me given the small size of the backup.

Once you finish your sync job, your backup should get pushed up automatically to Google Drive:

Tim Leland has a detailed blog post with instructions to set up a website on the Raspberry Pi to control Etekcity outlets. We'll be controlling the outlets via a Node.js app, so this post will show you the most direct way to get setup with the bare minimum.

Hardware

• Raspberry Pi - I have run this on a Raspberry Pi 3 and Zero W
• Etekcity outlets
• RF receiver and transmitter

You will need a breadboard or protoype board and wire up the receiver and transmitter to the appropriate pins:

Raspberry Pi pre-requisites

• Install Raspbian
• Run sudo apt-get update
• Run sudo apt-get upgrade
• Install Wiring Pi by running sudo apt-get install wiringpi

Note about Wiring Pi - the developer behind it is apparently going to cease development on it due to how he has been treated by the community. This is really unfortunate... He has released a final version for Raspberry Pi 4, but there won't be any versions past that. Eventually we'll need to find an alternative...

Leland's rfoutlet repo

Tim Leland's repository has two files we are interested in:

• RFSniffer - identifies RF codes
• codesend - transmits RF codes

We'll pull down his repo: git clone https://github.com/timleland/rfoutlet.git

I've created a outlet-test folder for my project, and I'm going to copy those two files over:

cp ./rfoutlet/RFSniffer ./outlet-test/RFSniffer

cp ./rfoutlet/codesend ./outlet-test/codesend

Reading RF outlet codes

As Leland details in his blog post, getting the RF codes for your outlets starts by executing ./outlet-test/RFSniffer which will will make your Pi start listening for codes to be transmitted. Then it is just a matter of hitting the On and Off buttons on the remote for each outlet and recording them. I typically write the On and Off codes directly on the outlets with a sharpie.

Transmitting RF outlet codes

codesend requires elevated privileges:

sudo chown root.root ./outlet-test/codesend

sudo chmod 4755 ./outlet-test/codesend

If everything worked, you should be able to transmit the RF codes you recorded earlier and start turning your outlets on and off:

./outlet-test/codesend 5239689

I thought there was going to be a Node.js app?

In order to transmit the RF codes via Node.js, we're going to spawn a shell and invoke the codesend executable that way:

import { exec } from 'child_process';
import { config } from './config'

exec(`./codesend ${config.onSignal}`);

setTimeout(() => exec(`./codesend ${config.offSignal}`), 10000);

The above code will turn the outlet on, and then turns it off 10 seconds after. It's a little dirty, but I'm now able to integrate with SignalR, react to IoT cloud-to-device messages, control power based on a sensor reading, etc...

Conclusion

This is a fun little project, and I have a number of little Pi Zero W's floating around the house controlling various lights and devices. With a little soldering know how and Adafruit's awesome Prototype Board for the Pi Zero, it's pretty straightforward to solder on the RF transmitter and create a permanent solution for power control.

Configuring Chrome DevTools

You will need to make Chrome on your laptop aware that it should be monitoring a particular IP and port on your LAN for a debugging stream.

Enable discovering network targets by navigating to chrome://inspect. Ensure Discover network targets is enabled and click the Configure button. Enter your Raspberry Pi's IP address and port, and click Done.

Coding our Hello World app

At this point you should have a share mounted on your Pi exposed to your laptop. I will be using VS Code to build the app. We will need to ssh into the Raspberry Pi using Putty or similar. We will create and enter a HelloWorld directory under our mount point:

mkdir /home/pi/Documents/Repos/HelloWorld

cd /home/pi/Documents/Repos/HelloWorld

We will create a Node skeleton app with a typical:

npm init (just accept all the defaults)

In VS Code, click File -> Open Folder and navigate to \\<RPi_IP>\PiShare\HelloWorld

Open package.json for editing and add a start-with-debug script:

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
    "start-with-debug": "node --inspect=0.0.0.0:9229 --inspect-brk index.js"
  },

start-with-debug does a couple things. The --inspect flag makes Node listen for a debugging client. --inspect-brk forces your app to break on the very first line of code, allowing you to attach you debugging client in time.

Create an index.js file with the following:

console.log("Hello");
debugger;
console.log("World");

Debugging our Hello World app

From within our Raspberry Pi shell, we execute npm run start-with-debug This will start our app, listen for a debugging client, and also break on the first line until a debugging client attaches.

If we switch back to our Chrome window on our laptop, we will see it has observed a debugging stream we can inspect:

Click the inspectlink and we will be greeted with a familiar debugging window:

There are three breakpoints set here. The --inspect-brk flag put a breakpoint on the first line. I added a debugger statement on the second line. Finally I added a manual breakpoint on the third line. Each one of them was respected and were broken on as expected.

First thing to do is burn an image of the latest Raspbian - Raspberry Pi's official operating system - onto an micro SD card. Don't skimp on the card, you want something that is reliable and fast. I got a pack of SanDisk Ultra 16GB and have had no issues, including when running Windows IoT Core which requires a lot speed.

I won't go over how to install Raspbian, as the official site does a great job and the recommended versions are updated regularly:

Installing operating system images - Raspberry Pi Documentation

This section includes some simple guides to setting up the software on your Raspberry Pi. We recommend that beginners start by downloading and installing NOOBS.

Raspberry Pi Documentation

You can either install NOOBS or download the latest version of Raspbian directly (which is Raspbian Buster at the time of writing). The Lite version is fine for IoT, which omits things like the desktop, which we won't need but would still consume resources.

Enable SSH

You can hook up a keyboard and monitor to your Pi and access your terminal that way, but it is easiest just to set things up headless.

After you have burned the Raspbian OS image to your SD card, open the card and simply create an empty file called ssh at the root. Your Pi will read that on boot and will enable SSH.

Configuring wifi

To configure wifi, create a wpa_supplicant.conf file at the root. This file is read by the Pi when it boots and allows you to configure a wifi connection.

The contents of wpa_supplicant.conf will be:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=<Insert country code here>

network={
 ssid="<Name of your WiFi>"
 psk="<Password for your WiFi>"
}

Note the country code is based on the ISO 3166-1 alpha-2 code standard.

Accessing your Raspberry Pi

If everything worked, you should now see a new raspberrypi device on your LAN.

Using Putty (or some other ssh client), you can now shell into your Pi:

You will be asked if you are certain you want to connect to this new device, click "Ok". Once you have connected, you will be asked for these credentials:

username: pi
password: raspberry

You should now have shell access to your Pi:

Update the hostname

If you plan on having multiple Pis on your network, they should each have a unique hostname so you can properly identify them. You need to update the name in two places:

sudo nano /etc/hostname There is a single line with raspberrypi written. Update it to whatever you wish your new hostname to be.

sudo nano /etc/hosts Find the line with 127.0.1.1 raspberrypi and update raspberrypi to your new hostname.

Here are what my files look like after renaming the hostname to newpi:

Reboot your Pi and the new hostname should be present in your LAN:

Assigning a static IP (optional)

As a convenience, we can ensure that when the Pi connects to the local network, it is assigned the same, predictable address.

Take care to keep track of the IP addresses you assign! If the same IP address is assigned to multiple devices, it will cause no shortage of issues and hair pulling.

As an alternative to a static IP, you can use something like DNSMasq which is installed on my router with dd-wrt firmware. By setting dhcp-host=C8:37:FB:5E:02:F3,newpi as an option, I can now ssh into it by specifying its address like newpi.hardie.lan Ensure you don't connect multiple devices on your network with the same hostname you have specified in a DNSMasq option!

To configure a static IP, we need to edit the dhcpcd.conf config file:

sudo nano /etc/dhcpcd.conf

There is a commented out template for setting up a static IP under "Example static IP configuration:"

We will use the template to assign a static IP to our wifi adapter:

interface wlan0
static ip_address=192.168.1.128/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1 8.8.8.8

Double check your router address, and then reboot your device. It will now always be assigned the static IP per the new configuration.

I'm unsure how applicable this is to other router firmware as I have been using dd-wrt exclusively for well over a decade, but if I assign a static IP to my Pi like this, dd-wrt will show a * for the hostname. Under Services, I need to configure a static lease and register the hostname with the MAC address.

Setting up a file share for Windows

If you are a crackerjack vim user, you can do all your coding inside your shell. But if you're like me and a few other people, you probably want a more fully-featured IDE. My setup has me coding using VS Code on my Windows laptop, but writing to my Pi where I can execute my code.

I need to create the folder I am going to mount:

sudo mkdir -p /home/pi/Documents/Repos

Change the owner to our pi account, which we'll also setup to be our networking account shortly:

sudo chown -R pi /home/pi/Documents/Repos/

In preparation of installing some dependencies, it's a good idea to do a system update:

sudo apt-get update

Once that is done, install a couple Samba dependencies:

sudo apt-get install samba samba-common-bin

If asked if you want to install a dhcp-client, answer yes. Once installed, open Samba's config file:

sudo nano /etc/samba/smb.conf

Ensure the workgroup property is set to WORKGROUP which is Window's default.

# Change this to the workgroup/NT-domain name your Samba server will part of
workgroup = WORKGROUP

Scroll to the bottom and add the following:

[PiShare]
 comment=Raspberry Pi Share
 path=home/pi/Documents/Repos
 browseable=Yes
 writeable=Yes
 only guest=no
 create mask=0777
 directory mask=0777
 public=no

We need a user account for authenticating a request to connect to our share. We will use the existing pi account:

sudo smbpasswd -a pi

Enter your Samba password twice and then resart Samba:

sudo systemctl restart smbd

Before we open the share, let's put a file in it:

sudo touch /home/pi/Documents/Repos/hi-there.txt

Open Windows Explorer and enter the IP of the Pi (in my case 192.1.68.1.128 followed by the name of the share (PiShare): \\192.168.1.128\PiShare

You will be asked for your network credentials, remember to qualify your username with your hostname you setup earlier. The default would be raspberrypi but in my case I updated my hostname to newpi so my qualified username is newpi\pi . My password is the Samba password I set a couple steps ago.

If everything we well, you should now be able to browse the share:

Installing Git

Source control is mandatory for any serious dev work. I have Gitlab setup on my Synology DiskStation, so I need to install git on my Pi and some ssh keys to connect.

sudo apt-get install git

How you connect to git - https or ssh - will depend on your installation. I use ssh keys so at this point I would copy my keys over to ~/.ssh so that I can authenticate with Gitlab and pull down my projects to be run on my Pi.

Installing Node on Raspberry Pi (optional)

I do a lot of Javascript programming, and many of my IoT projects are written in Node, so Node is a standard part of my setup. Python is already installed in the Pi, so if you are going to use that, you can skip this section entirely.

Installing Node is a little bit more involved. I don't use apt-get as I've never got it to work properly on a Pi Zero, and there is also a conflicting node package on Debian (the OS Raspbian is based on) so we would need to install nodejs and create a symlink, which seems like a bit of bother.

To that end, the following instructions should be universal for setting up Node on any Pi version. But to know what version of Node to download, we need to get the processor architecture of our device:

uname -m

That will print out something like arm71 or armv6l. Next we visit the Node download page and find the latest LTS version. My Pi 3 is advertising a arm71 processor, so I will download and extract the package like so:

wget https://nodejs.org/dist/v12.13.1/node-v12.13.1-linux-armv7l.tar.gz

tar -xzf node-v12.13.1-linux-armv7l.tar.gz

Copy the extracted contents to /usr/local:

sudo cp -r node-v12.13.1-linux-armv7l/* /usr/local

Check installation went alright:

node --version

You should get something like v12.13.1

const myData = ["foo", "bar", "baz"]

interface Props {
  myData: "foo" | "bar" | "baz"
}

class MyClassCore<Props> { ... }

export const MyClass withMyData(mydata, MyClassCore);

In the above contrived example, I need to maintain both the string array and the union type. An improvement would be to derive the union type from the array so that if we need to update the data, we would only need to update the source array and the changes would apply to the union type automatically.

The easiest way to do this is by first creating an immutable tuple of literals using the as const assertion.

const myData = ["foo", "bar", "baz"] as const; // readonly ["foo", "bar", "baz"]

From here you have a couple ways to derive the union type. The first is to "use the property type from the numeric index signature" with this syntax:

type MyDataUnion = myData[number]; // "foo" | "bar" | "baz"

A colleague had another way of doing the above that reads a little more straightforward to me:

type ExtractArrayItemType<T> = T extends ArrayLike<infer U> ? U : never;
type MyDataUnion = ExtractArrayItemType<typeof myData>; // "foo" | "bar" | "baz"

Because the array is immutable, Typescript can safely infer that the type is "foo" | "bar" | "baz" - the narrowest type - instead of string[] or even ("foo" | "bar" | "baz")[] as those types are mutable.

if (someFunction) {
  someFunction();
}

As a minor convenience, I usually write a function that will enact that guard for me:

function guardInvoke(func, ...args) {
  if (func) {
      func(args)
  }
}

Then I would write invoke my functions like this: guardInvoke(myFunc, 1, 2, 3)

Moving to Typescript, we can still use the guard, but we should declare more types to make the function more type-safe. To do this I leverage some black magic types from the core Typescript lib.es54.d.ts library

Diving into Parameters<T> and ReturnType<T>

Paramters<T>: Obtain the parameters of a function type in a tuple

ReturnType<T>: Obtain the return type of a function type

The type definitions are similar and interesting, but let's have a look at Parameters<T>:

type Parameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? P : never;

This can be pretty intimidating for the uninitiated, so let's break this down:

type Parameters<T extends (...args: any) => any>

All this means is T must extend (...args: any) => any - in other words T must be any function. Why doesn't T simply extend the Function type? We are going to need a reference to ...args in the next part.

T extends (...args: infer P) => any ? P : never;

This is a conditional type and will select one of two possible types based on the condition (just like a ternary!)

What is a bit unusual (at least when I first started looking at these) is that the condition appears to be gratuitous. Why do we need to evaluate the condition that T is a function? We already constrained type T to a function in the Parameters declaration, the compiler would complain as soon as you attempt to type T to anything but a function!

The answer is that while the evaluation of the condition will always result to true, conditional types can provide us type inference. The conditional type can include infer to determine types when the conditional evaluation succeeds. So given the conditional type declares parameter  ...args with infer P, we will return type P when the condition evaluates to true (which it always will!) This is how Parameters<T> identifies parameter types in functions.

ReturnType<T> is very similar, but worth a look as well.

Where's that guard you were talking about?

Based on those core types, I was able to re-create my guard function with type-safety in Typescript:

/**
 * Invokes a function if not undefined or null
 * @param func - a possibly undefined or null function
 * @param args - the function argument
 * @returns The function's return, or undefined if function is undefined or null
 */
export function guardedInvoke<F extends ((...args: any[]) => any) | undefined | null>(
    func: F,
    ...args: F extends ((...args: any[]) => any) ? Parameters<F> : any[]
): (F extends ((...args: any[]) => any) ? ReturnType<F> : never) | void {
    if (func) {
        return func(...args);
    }
}

guardInvoke will take a function argument, and make sure it isn't a bottom value before invoking it. Using the same black magic of conditional types with type inference leveraged by Parameters<T>, we're able to get compiler safety and IDE hinting.

let addNumbers: ((...args: number[]) => number) | undefined;
let concat: ((arg1: string, arg2: string, arg3: string) => string) | undefined;

console.log(guardedInvoke(addNumbers, 1, 2)); // prints undefined
console.log(guardedInvoke(concat, "foo", "bar")); //prints undefined

addNumbers = (...args: number[]) =>
    args.reduce((previous, current) => previous + current, 0);

concat = (a: string, b: string, c: string): string => `${a}${b}${c}`;

console.log(guardedInvoke(addNumbers, 1, 2, 3)); // prints 6
console.log(guardedInvoke(concat, "foo", "bar", "baz")); // prints "foobarbaz"

guardInvoke(addNumbers, "foo"); // ERROR
guardedInvoke(concat, 1, 2);// ERROR

UPDATE: Now that version 3.7 is available, optional calling is available to us via the new ?. operator

addNumbers?.(1, 2, 3) // Will only be invoked if addNumbers exists  

• this blog I just setup
• the feed from an IP camera I installed in the garage (I'm a bit OCD and there have been occasions where I have forgotten to close the garage door - this lets me quickly check that the garage is indeed secure from my phone)

Reverse proxies can be installed on routers, but the router I have runs dd-wrt firmware, and it is a bit cumbersome to get it setup. Fortunately Synology includes a reverse proxy with its DiskStation operating system, and it's a breeze to setup.

Port forwarding

The first step is to forward HTTPS requests to the router onwards to your DiskStation. How to do this varies from router to router, but you want to forward HTTPS requests on port 443 to your DiskStation's IP address (mine is 192.168.1.25) on the same port. My rule looks like:

Domain name

You'll need to get a domain name for a few reasons:

• you'll need subdomains to support routing to different resources (e.g. camera.my-domain.com and blog.my-domain.com)
• you'll probably want to use a Dynamic DNS service to keep your domain pointed at your DiskStation when your ISP changes your IP address, which is typical for residential accounts
• you'll need a domain to procure a SSL certificate required for secure HTTPS communication

Getting a domain name is out of scope of this post, but if you're ok with not using a completely custom domain, you can piggyback off one of Synology's domains and leverage their DDNS service. (At the time of writing this, I'm using hardiegras.myds.me for my domain.)

Configuring the Reverse Proxy

I need to create a routing table so that the proxy knows where to direct requests. I want to route:

• blog.hardiegras.myds.me -> 192.168.1.25:2368
• camera.hardiegras.myds.me -> 192.168.1.178:30001

"blog" and "camera" are subdomains I came up with myself, they can be anything.

Open Control Panel -> Application Portal and open the Reverse Proxy tab:

Note that I can target any resource that's on my home network, not just resources on the DiskStation.

SSL Certificate

The HTTPS protocol requires an SSL certificate installed on the DiskStation. In addition to that, the certificate must be signed by a trusted authority in order to avoid your sites being served with a "Not Secure" warning. Fortunately, Synology has made this very easy to do.

Open Control Panel -> Security, and open the Certificates tab:

Click on the Add button, select "Add a new certificate" and click Next:

Select "Get a certificate from Let's Encrypt" and click Next

Enter your domain qualified with the subdomain from the reverse proxy's routing table:

Once you click Apply, Let's Encrypt will generate your certificate and it will be installed automatically onto your DiskStation:

Note the expiration date - the certificate will need to be renewed every few months.

Final step is to click Configure and map the certificate to the service you want to expose:

Now your DiskStation will serve HTTPS requests with a certificate from Let's Encrypt, a trusted authority. Browsers will now show a padlock when users visit to show that everything has been secured properly:

Note that much of this setup is a modified version of what is described in Dmitry Fisenko's blog post

Standing up Ghost CMS on my Synology NAS required a few dependencies

• MariaDB 10
• phpMyAdmin
• Docker

UPDATE: Turns out the docker image always uses SQLite for a database, MariaDB is not required at all.

Install Ghost

Once your database and account have been created, open Docker and download the Ghost image from the Docker registry:

Once you launch your image, you will need to specify some settings:

Under Advanced Settings I turned on auto-restart:

Under Volume, we are going to specify a mount point our Ghost CMS container will use to durably persist static content. Click "Add Folder" and then create a new directory called "blog" under "/docker", and mount to "/var/lib/ghost/content"

Under network, we select "Use the same network as Docker host". This will expose our database on 127.0.0.1.

Click on environment and set this variable:

url=https://domain.com

After you have created the container you can check its status in the "Container" tab

Double click the container and you'll be able to view logs which will help troubleshoot any isssues. If your container launched successfully, the tail of the log will indicate Ghost's URL:

Append the port from the log onto the IP address of the NAS to get your base URL - in my case its 192.168.1.25:2368

Navigating to 192.168.1.25:2368/ghost will allow you to configure Ghost.