Dan Benitah

Azure Digital Twins (ADT) Explorer

danuw@volto.io — Wed, 02 Jun 2021 00:00:00 GMT

Since last summer, a great tool was made available to easily browse Azure Digital Twins v2's graph called the ADT Explorer.

First and foremost, it allowed you to visualise your graph, and for those who tried, this was absolutely crucial in validating it all made sense (e.g. to identify "orphans" for missed relationships - are all floors linked to a building, all occupancy sensors links to a desk etc...).

It also allowed for some editing capabilities, such as the ability to import a graph or models, create twins and relationships. It was especially useful to be able to edit basic properties on the fly (for testing or demo purposes).

To run that tool though, you either could do it locally (which I mainly relied upon), or deploy your own instance (including some configuration for each instance).

They have now announced a publicly available instance at https://explorer.digitaltwins.azure.net/ as well as run through of its awesome latest capabilities, such as:

filtering the loaded graph: for big instances, it used to take a while to load a full graph (all nodes and relationships), it now seems to load much faster and simply allows to more easily single out or highlight some nodes or groups of nodes from these key words

model graph: which similar to what I started doing here enables straight in the explorer to visualise relationships between models

I am really excited about how these new features will improve my productivity and the productivity of my teams and colleagues.

Be sure to keep an eye on the enhancement requests and/or contribute for these to come to life faster :)

One more things...

In the event you get an unauthorized error and are not able to change the directory (blank list) as shown below, there is currently a work around by using the following URL format:

https://explorer.digitaltwins.azure.net/?tid=<TENANT_ID>&eid=<ADT_HOSTNAME>

References:

https://explorer.digitaltwins.azure.net/
IoT Show episode: https://youtu.be/qbs6XRlIxes
ADT explorer repo : https://github.com/Azure-Samples/digital-twins-explorer

DTDL models inheritance

danuw@volto.io — Sun, 20 Dec 2020 00:00:00 GMT

Digital Twin Language Definition (DTDL) is brilliant and helps standardize how to create your twin models and how they relate to each other. How about using it also to generate documentation in combination with mermaid?

Mermaid "lets you represent diagrams using text and code". It makes it very easy to generate from what you are doing. Take a look at the samples in the online editor for reference.

I first heard of mermaid in the Azure DevOps context, but I really first started getting value out of it, by using the mermaid flow chart to represent the digital twin graphs we would generate through an import process. We would therefore get visual confirmation of what had been imported (a bit like what ADT Explorer is now used for).

However, I recently wondered how I could document the hierarchy I had in my /Models folders alongside with the code, and got inspired by the class diagram type of diagrams this time. That would help visualise the inheritance (through DTDL's extends property), and likely the main properties each model would each bring as part of their extendability.

DTDL defines that you can extend with up to 2 interface at the time of writing.

How to generate the graph?

To get started quickly is very easy using dotnet core with the following steps:

Create a project
Add newtonsoft.json package
Use Json2csharp to get strongly typed classes of your models and import into your project
Iterate through your models and output as text the data (extendability and properties)
output to console and/or file
Generate diagram from output

Set up the project

Note the source code is available at https://github.com/danuw/AdtGraphModel and uses models from ADT explorer or realestatecore ontology as examples.

Create a new folder and browse to it.

mkdir AdtModelsGraph
cd AdtModelsGraph/

Create the console app and add the Newtonsoft.Json nuget package.

dotnet new console
dotnet add package Newtonsoft.Json

(optionally) Make sure it all compiles and carry on...

dotnet build

Generate the classes

Using a combination of your models you may end up with the following classes using json2csharp.com.

  public class Property    {
      public string name { get; set; } 
      [JsonProperty("@type")]
      public string Type { get; set; } 
      public string schema { get; set; } 
  }

  public class Content    {
      [JsonProperty("@type")]
      public string Type { get; set; } 
      public string name { get; set; } 
      public object schema { get; set; } 
      public bool? writable { get; set; } 
      public string displayName { get; set; } 
      public List<Property> properties { get; set; } 
  }

  public class Root    {
      [JsonProperty("@id")]
      public string Id { get; set; } 
      [JsonProperty("@type")]
      public string Type { get; set; } 
      public string displayName { get; set; } 
      [JsonProperty("@context")]
      public string Context { get; set; } 
      public List<Content> contents { get; set; }
      public List<string> extends { get; set; } 
  }

Extract the data in a mermaid format

Looking back at the examples, we can construct that graph using the following steps:

start with classDiagram and subsequently use correct indentation for the connections
Inheritance connections for classes (which we will use for DTDL interfaces) are represented with this pattern Class1 <|-- Class2 as in Vehicule <|-- Car or Animal <|-- Chicken
Properties use this pattern Class1 : +PropertyType PropertyName such as Vehicule : +Integer NumberOfWheeels
Methods (which we will use for relationships) use this pattern Class1 : +MethodName() such as Vehicule : +MoveForward() and in our case Building : +contains()

So, first, make sure you add the Newtonsoft.Json in the usings, although you will be needing the following ones:

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Text.Json;
using Newtonsoft.Json;

Then lets create these connections between classes, and list the contents.

static void Main(string[] args)
{            
    Console.WriteLine("Hello World!");

    var currentDir = Directory.GetCurrentDirectory();
    var docPath = Path.Combine(currentDir, "Models");

    var models = Directory.EnumerateFiles(docPath, "*.json", SearchOption.AllDirectories);

    var sb = new StringBuilder();
    var sbProps = new StringBuilder();
    sb.AppendLine($"classDiagram");

    // Step 1 : Iterate through each model and save model id and relatioinship in mermaid format
    foreach (var m in models)
    {
        var myJsonString = File.ReadAllText(m);
        var model = JsonConvert.DeserializeObject<Root>(myJsonString);
        
        // Step 1.a : Record the inheritance
        if(model.extends !=null)
        {
            foreach (var e in model.extends)
            {
                sb.AppendLine($"    {GetName(model.Id)} <|-- {GetName(e)}");
            }
        }
        else // In cases where a model does have any inheritance so we can add properties to an existing "class"/model (and avoid errors)
        {
            sb.AppendLine($"    class {GetName(model.Id)}{{");
            sb.AppendLine("    }");
        }

        // Step 1.b: If there are properties, record them for that "class"
        if(model.contents == null)
            continue;

        foreach (var c in model.contents)
        {
            var s = c.schema as string;
            if(c.Type.Contains("Relationship") )
            {
                sbProps.AppendLine($"    {GetName(model.Id)} : +{c.name}()");
            }
            else if(s == null || s.Contains("{") || s.Contains(":")){ // Complex type, simplified as "Object" for now
                sbProps.AppendLine($"    {GetName(model.Id)} : +Object {c.name}");
            }
            else
            {
                sbProps.AppendLine($"    {GetName(model.Id)} : +{c.schema} {c.name}");
            }   
        }
    }

    // Step 2 : Output the results
    var mermaidPath = Path.Combine(currentDir, "mermaid.mmd");
    Console.WriteLine(mermaidPath);

    // output all the recorded connections to create a mermaid graph of the relationships
    var mermaid = sb.ToString() + sbProps.ToString();
    Console.WriteLine(mermaid);

    // Save it to file to view in a mermaid (pre-)viewer.
    File.WriteAllText(mermaidPath, mermaid);

    Console.WriteLine($"Mermaid saved to {mermaidPath} ");
}

Above, we only differentiate between Property and RelationShip in contents. I may in the future, start to differentiate between Property and Telemetry as this is easily missed difference at first.

Finally, model id characters are not accepted so here we are simplifying the names by removing the domains and keeping the version, but this should be adapted to the complexity of your scenario.

    static string GetName(string id){
        var position = id.LastIndexOf(":");// I believe that charater is mandatory so no extra check needed here to ensure it does not fail (safe assumption)
        id = id.Substring(position+1);// removing the domain info from id
        return id.Replace(";", "");// removing the ';'and keeping the version
    }

Find the complete code at https://github.com/danuw/AdtGraphModel.

Convert to diagram

Finally, visualise the converted diagram using some of the many options such as mermaid-cli, or one of the mainly previewing extensions in VS code for example. An easy one remains the online editor at https://mermaid-js.github.io/mermaid-live-editor/. You can also use the npm package (try npx version of the cli for a quick and clutter free test to install packages and execute on the fly), to generate a transparent svg and/or complete the automation of getting your relationships into a diagram locally.

Finally...

Whether you were asked, or you simply needed it for yourself, this should now give you a great way to document your models going forward.

This is especially useful when you want to make some updates and refactor/refine models' inheritance and/or properties.

This is still a very basic implementation though, which, for example, does not cover complex data types, so feel free to help extend it.

References:

Mermaid online editor at https://mermaid-js.github.io/mermaid-live-editor/
Example models from:
- ADT explorer at
- Azure RealEstate Ontology at https://github.com/Azure/opendigitaltwins-building/tree/master/Ontology

New query COUNT functionality for Azure Digital Twins

danuw@volto.io — Mon, 12 Oct 2020 00:00:00 GMT

A quick one in case people did not notice it is now possible to use COUNT in queries to the Digital Twins v2.

Very basic, but makes a big difference in practice.

SELECT COUNT() FROM DIGITALTWINS

returned ...

{
  "COUNT": 547
}

Should help with a lot of basic scenarios for showing totals on dashboards, notifications badges, or simply paging...

Anyway, more on queries at https://docs.microsoft.com/en-us/azure/digital-twins/how-to-query-graph#count-items

SPFx not appearing on refresh anymore!

danuw@volto.io — Tue, 15 Sep 2020 00:00:00 GMT

Last summer I started looking a little bit more into SPFx development, having to port a very basic HTML/CSS/JS component from content editor WebPart to Modern SharePoint site (where iFrame was not a viable option).

After I successfully, though basically, ported my code over, my deployed package started disappearing on page refresh whether it was while saving a draft or while publishing the page. When editing the page, the WebPart container would still look bigger, as if a ghost of my web part was still there and duplicating that section would reveal the app in the new copy until the next save and refresh cycle.

I like to start versionning to the minimum so I can incrementally get a first minor version as the first draft.

This issue occurring on refresh, I could not easily undo the last thing I had done, as I had "made changes -> refreshed -> made changes -> ..." a few times.

We were striping the code of anything that could be the issue and that is when it struck me: I had read (and I cannot find where anymore) that data version was meant to be only two parts, so:

    protected get dataVersion(): Version {
        return Version.parse('1.0');
    }

as opposed to

    protected get dataVersion(): Version {
        return Version.parse('0.0.1');
    }

Changing this back and forth confirmed this was the exact issue.

Even though the answer was in my head from something I had read while the app was still working, I still needed some help, so, I hope this helps some out there (and do let me know if you found where this is in the documentation so I can add a reference - thanks).

Using tags with Azure Digital Twins

danuw@volto.io — Tue, 01 Sep 2020 00:00:00 GMT

The latest version Azure Digital Twins' DTDL (Digital Twin Definition Language v2) supports a wide variety of schemas.

One of them is the ability to add tags using a Map.

The documentation found here shows you how to leverage the Map type to add marker or value tags.

The following in the case of a value tag.

{
  "@type": "Property",
  "name": "tags",
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "tagName",
      "schema": "string"
    },
    "mapValue": {
      "name": "tagValue",
      "schema": "string"
    }
  }
}

... but I did not easily find examples of how to create new twins in code using these more complex schemas (Map, Array, Enum, object).

So to stay on the example from the Microsoft's documentation, to add tags using the Map schema, you can create a Dictionary<string, string> to add tags to your metadata as follows.

myTwinMetadata.Add($"tags", new Dictionary<string, string>() { { "red", "" }, { "size", "large" } });

What would or do you use the tags for?

Feel free to message on twitter to let me know...

Asking for confirmation when using Microsoft Power Automate and Planner

danuw@volto.io — Tue, 25 Aug 2020 00:00:00 GMT

As discussed in my previous post, posting via flow immediatly after people would inadverdetly tick a box (which completes that task) would not allow deleting that message on the channel. So we needed to give a chance to people to correct that mistake before Flow would post that message.

The solution seemed to use a timeout. We wanted the post to happen pretty quickly after completion of the task, but like the "delay send" functionality in mailboxes, here we needed to say: "give it 5 minutes!".

It is possible to "configure run after" actions that activate on error, time out etc... When timing out, the whole flow was failing and it was not possible to go ahead and post anymore.

That is how I found out about the Try/Catch/Finally pattern and how to apply it to flow. In our case here, finally is not necessary.

Here we are using try/catch on the confirmation request and response or non response/time out. Should the user respond, we record his choice in a variable and act according to his response. Should it time out, we assume the completion was intentional and go ahead.

Initialise a variable to track the response
Try and get a response
Catch any issue

Send messages accordingly

THAT's IT! (should work like a charm ;)

I had issues getting the confirmation working (trial and error on the syntax), so I hope the screenshots help.

Thank you...

Resources:

Try Catch main reference

Querying Rigado data through IoT Central

danuw@volto.io — Fri, 07 Aug 2020 00:00:00 GMT

Quick one around querying IoTC Rest API to retrieve the last known values of some of your Rigado connected sensors...

It starts with the device template which contains the important information:

property name you are after
property type
property's interface name

Using the device id, we will then use the following to find out the interface name:

https://{{IOTC-name}}.azureiotcentral.com/api/preview/devices/{{deviceId}}/components

In my case it returns something like that:

{
    "value": [
        {
            "@id": "urn:rigado:HoboMX100:HoboMX100:2",
            "@type": [
                "InterfaceInstance"
            ],
            "name": "HoboMX100",
            "displayName": "HoboMX100"
        },
        {
            "@id": "urn:rigado:HoboMX100:DeviceInformation_HoboMX100:1",
            "@type": [
                "InterfaceInstance"
            ],
            "name": "DeviceInformation_HoboMX100"
        },
        {
            "@id": "urn:rigado:HoboMX100:IoTDevice_HoboMX100:1",
            "@type": [
                "InterfaceInstance"
            ],
            "name": "IoTDevice_HoboMX100"
        }
    ]
}

We can then form the query to get our property value.

Temperature, for example, used the HoboMX100 interface and was a telemetry property

... so it will be requested like that:

https://{{iotcname}}.azureiotcentral.com/api/preview/devices/e25f2ace9e55/components/HoboMX100/telemetry/temperature

{
    "value": "12.73700287704178",
    "timestamp": "2020-08-03T22:47:42.442Z"
}

... while the battery Level was a telemetry from the IoT Device interface called IoTDevice_HoboMX100

... so it will be requested like that:

https://{{iotcname}}.azureiotcentral.com/api/preview/devices/e25f2ace9e55/components/IoTDevice_HoboMX100/telemetry/batteryLevel

Curious to know you would use this for...

References:

Using Microsoft Power Automate and Planner to automate praise

danuw@volto.io — Tue, 04 Aug 2020 00:00:00 GMT

This year, my company had an Azure certification challenge and the team started to track people's certification status using planner. That helped them understand better who was planning to get what certification by which date and whether it was "completed".

Flow (or Power Automate) has a few available triggers and action for planner.

So while it does not offer anything (at the time of writing) when a task is updated (in our case the bucket was used to track status), it does offer a trigger when a task completes which is what we will be using here.

The scenario was to use flow to post an adaptive card to the related channel announcing to everyone someone had passed an exam and encourage discussion and praise(congratulations, tips, etc...).

While you may think of some other scenario to apply this to, this is what we used:

For the praise's adaptive card, you will likely want to design it here: https://adaptivecards.io/designer/.

You can also start from some of the examples at https://adaptivecards.io/samples/.

That has turned out to drive great engagement on the channel and almost fostered motivation to pass the exam and be the one to get the praise.

So far, the only issue has been that once a message has been posted as the Flow bot, it cannot be updated. So if the task was marked as completed in error, the post cannot be deleted. So that certainly is something to update in the future.

Other possible improvements:

Flow message to user on registration (creation of task) to help with resources linked to certification
Flow message on completion to confirm next steps ("don't forget to register your cert at this link", "people usually do this cert as the following exam"...)
automation around reminders when date approaches (Planner has built in reminder already so whatever it does not cover :-P )
auto suggestion on people to create a study group with

Azure Digital Twins new Multi join query feature

danuw@volto.io — Sun, 02 Aug 2020 00:00:00 GMT

Microsoft's Azure Digital Twins Preview v2 team has released a new feature. It allows to query the twin graph with up to 5 joins.

Concretely, what that has meant for me is that I can surface some aggregates a lot more easily. In my case, I have a list of buildings, that have floors, that have zones, that have desks and rooms (aka Spaces), and finally that have sensors.

I needed to be able to run quick aggregate from the building or floor perspective. For example, using occupancy sensors, this allows me to quickly find out occupancy per floor.

The following would return all the nodes (all sensors in my case) contained in my spaces (i.e. desks and rooms):

SELECT Sensor
FROM DIGITALTWINS Building
JOIN Floor RELATED Building.contains
JOIN Zone RELATED Floor.contains
JOIN Space RELATED Zone.contains
JOIN Sensor RELATED Space.contains
WHERE Building.$dtId = 'myBuildingId'

See github issue for references.

What challenge did that solve for you? Use Twitter (#AdtMultiJoin?) to let me know... :)

Azure IoT Hub test data using Particle Internet Button

danuw@volto.io — Mon, 01 Jun 2020 00:00:00 GMT

Particle internet buttons as IoT hub test data source.

Use a Particle internet button to create test data for your Azure IoT projects ...

Context

On one of my recent IoT projects I needed a quick way to interact with IoT Hub to create test occupancy and temperature data. That was what fitted best my scenario but feel free to adapt this to your needs.

I recycled an unused Internet button once used for tracking (DevOps) builds, by setting up simple button clicks to:

publish an event as occupied or available to the iot hub
publish changes of temperatures to the IoT (increment temperature between two thresholds easily and update the LEDs to confirm)

In short...

The basic idea is to use the internet button sample that publishes different events on some of the button clicks and use the integration to send a custom payload.

So you can click the different available buttons to trigger different payloads of test data

Set up your device

To get started quickly with the most basic implementation, simply:

look for the InternetButton library on the Particle Cloud (using https://build.particle.io)
select the most "advanced" example (basically the last one number 9) - and flash it to your device.

Configure the integration to IoT Hub

You can set whatever payload you want using handlebars (see here for more documentation).

Set the integration payload

Use it to set static or dynamic properties.

Static payload

In the following example, IsOccupied is set to always send true. You could consider sending false when clicking another button such:

button1 -> occupied
button3 -> free

{
    "event": "{{{PARTICLE_EVENT_NAME}}}",
    "data": "{{{PARTICLE_EVENT_VALUE}}}",
    "device_id": "{{{PARTICLE_DEVICE_ID}}}",
    "published_at": "{{{PARTICLE_PUBLISHED_AT}}}",
    "IsOccupied": true
}

Dynamic payload

You could also customise the code to change a temperature property before it publishes an event such as:

button2 -> decrement temperature by 1 degree and then publish
button4 -> increment temperature by 0.5 degree and then publish

You would then use a similar json data template to this:

{
    "temperature": "{{{temperature}}}"
}

If you are going to be handling json, I would recommend using ArduinoJson and publish using that json data. Checkout the examples for ways on how to use it - I personally used this article to get started quickly.

Video

I go through that process in that video if that helps.

So...

The above is a flexible base. We are giving a temperature or occupancy example, but you could also use it for any types of gauge simulation (battery level, signal strength, fuel tank level etc...)
If you are working with third parties, you can easily simulate their payload via the Particle Cloud integration interface

You probably have all sort of test data generators lying around but I found this very practical for quick tests to check everything is going as expected, and simulating predefined sensor data during demos for perfectly times effects.

Automate daily time-lapses

danuw@volto.io — Fri, 28 Feb 2020 00:00:00 GMT

Looking back at picture of how the garden evolved throughout the spring and summer, I kept on thinking that a time-lapse of this would look incredible. I once did a time-lapse of the outside and you have to admit that looking at the clouds at that speed really makes a great sight and this is how the idea came to life.

So although the one about the garden is still in the works, following are instructions on how to automate daily time-lapses of your outside view.

Also we will be using a raspberry pi, IP camera and docker.

I assume the raspberry pi to be already set up (nothing special, just accessible via ssh or that you can use the terminal).

if you have a Pi Camera, feel free to use the following to take your pictures doc for raspistill.

Step2.1 - Install Docker on the Raspberry pi

Might be able to use this now: https://docs.microsoft.com/en-gb/azure/iot-edge/how-to-install-iot-edge-linux#install-the-container-runtime

curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list

sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/

curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/

sudo apt-get update

sudo apt-get install moby-engine
sudo apt-get install moby-cli

Step 2.2 - Create folder structure and set up the cron

mkdir ~/timelapse

cd ~/timelapse

mkdir -p ~/timelapse/output/today

Let's create the script file to take that picture

nano ~/timelapse/takephoto.sh

Paste the following

#!/bin/sh
today=`date '+%Y_%m_%d_%H%M_%S'`;
filename="/tmp/ffmpeg/picture_$today.jpg"

sudo docker run -v=/home/pi/timelapse/output/today:/tmp/ffmpeg —rm mhiro2/rpi-ffmpeg:3.3 -rtsp_transport tcp -i "rtsp://admin:<yourpassword>@<your iP of type 192.168.0.x>:554" -vcodec mjpeg -frames 1 $filename

Try it

~/timelapse/takephoto.sh

To test, check the output using

ls ~/timelapse/output/today

If you have an issue with permissions, I used the following but that may be too much actually : sudo chmod a+rwx ~/timelapse/takephoto.sh

If you can see a file, you can also download it to check what it looks like

scp [-P <port number>] pi@192.168.x.x:/home/pi/timelapse/output/taday/* .

Set up the crontab

crontab -e

(I chose 1 for nano if you are asked to confirm because it is the first time you set up then cron)

On new line at the end, add:

* 07-18 * * * /home/pi/timelapse/takephoto.sh

... where we basically ask for that job to take a photo every minutes between 7am and 6.59pm.

You can then check a few pictures were taken using again the command

ls ~/timelapse/output/today

Making the time-lapse

nano ~/timelapse/move_and_convert_to_timelapse.sh

#!/bin/sh
today=`date '+%Y_%m_%d_%H%M_%S'`;
foldername=`date '+%Y_%m_%d'`;

filename="/tmp/ffmpeg/timelapse_$foldername.mp4"
targetFolder="/home/pi/timelapse/output/$foldername"

#Ensure the folder exists
mkdir -p $targetFolder

#Move today's pictures into a different folder
mv -f /home/pi/timelapse/output/today/* $targetFolder

#Rename all pictures
aa=0;for i in `ls $targetFolder/*`; do mv $i $targetFolder/`printf "%04d" $aa`.jpg; aa=$(($aa+1));done

#Create the time-lapse from the pictures
sudo docker run -v=$targetFolder:/tmp/ffmpeg mhiro2/rpi-ffmpeg:3.3 -r 30 -i /tmp/ffmpeg/%04d.jpg -r 10 -vcodec libx264 -vf scale=1280:720