/tutorial-generated-library-from-conceptual-model-with-azure-services

Primary LanguageC#MIT LicenseMIT

Tutorial - Generated library from Conceptual Model with Microsoft Azure services

This document describes how to develop Digital Twins & IoT Solution by using Conceptual Modeling for Business scenarios and subject matters.

The "Conceptual Modeling" is extension of xtUML based modeling techniques for visualizing business, taking into account my knowledge and experience. With the tools and services presented in this document, you can model your business using BridgePoint, a dedicated conceptual moderling tool, to build not only scalable Digital Twins solution on a cloud but also IoT device application with minimul effort.
For more information on Conceptual Modeling, please read "Art of Conceptual Modeling".

The big picture of developing solution

The following services are used to build solution.

The architecture of the solution that can be developed is as follows.

solution architecture

  • Secure device connectivity and two-way communication with services using Azure IoT Hub
  • Current state of conceptual instances and relationship is hold into Azure Digital Twins, which is very compatible with Conceptual Modeling
  • Execute behavior based on business scenario and maintain consistency int conceptual world with a C# code library automatically generated from a Conceptual Model created by BridgePoint.

Overview of build solution process

Twin Models described by DTDL and most of the logic of Azure Functions and IoT device application relies on artifacts automatically generated from the Conceptual Model.
The generated parts are shown as follows.

process overview

The generators shown in the figure are published from the following repositories.

All generators are also published as NuGet Packages. You can built-in these generator into your DevOps pipeline.
All Generators are developed using "Implementation by Translation(This techinique is established in Shlaer-Mellor method and xtUML)".
For more information on "Implementation by Translation", please read "Technique of Tranfromation".

The solution consists of parts that are automatically generated from your conceptual model and fixed code on Azure Functions that don't depend on idividual conceptual models.

The name of the Azure Functions are as follows.

Name of Azure Functions

All Azure Functions are published from Github.

  • ReceiveD2CToTwinGraph - ReceiveD2CToTwinGraph.cs
    • Completely independent formally of indivisual Conceptual Model
  • ReceiveReportedPropertiesToTwinGraph - ReceiveReportedPropertiesToTwinGraph.cs
    • Completely independent formally of indivisual Conceptual Model
  • DomainModelExecutor - DomainModelExecutor.cs
    • The code itself is formally independent of individual conceptual models.
    • Run with domain model C# code libary automatically genenerated from conceptual model.
  • TelemetryNotified - TelemetryNotified.cs
    • The code itself is formally independent of individual conceptual models.
    • Run with domain model C# code libary automatically genenerated from conceptual model.

Step by Step.

This section will explain the procedure step by step.

1. Create Conceptual Model for your business

First of all, building a conceptual model by BridgePoint based on subject matter and scenarios your business works with.
To learn how to use BridgePoint, please refere to "ビジネスをモデル化する ～ BridgePoint を使ってみよう".
I have released training tutorials to build better modes, please refer to "概念モデリングチュートリアル集".

If you have not enought conceptual modeling skill, please use sample model.

2. Generate Twin Model by DTDL

Use DTDL Generator to generate Twin Models from Conceptual Model constructed by BridgePoint.
This generator can generate DTDL file for both Twin Graph on Azure Digital Twins and IoT Plug & Play (IoTPnP) Model from same conceptual model.
When you write following text on the description of conceptual information class,

@iotpnp

The generator generate 2 DTDL files from the conceptual information class. If the name and key letter of the conceptual information class is 'Device','D' and specified namespace is 'dtmi:com:company', generated files are as follows.

  • Device.json
    • @id - dtmi:com:company:D;1
  • Device_iotpnp.json
    • @id - dtmi:com:company:D:iotpnp;1

You can control how property of conceptual information class are generated as DTDL by coloring for the property.
When you write following text on the description of a property which you'd like to control.

@iotpnp(deviceid,exclude)

Generator generates DTDL Property only on Twin Graph side because Azure IoT Hub automatically put Device Id into telemetry message from IoT Device to the service side, so the IoT device application doesn't need to send the device id.

Next, when you write

@iotpnp(telemetry)

, Twin Graph side generates as Property, IoT PnP side generates as Telemetry. By this feature, you can realize situation described on https://learn.microsoft.com/azure/digital-twins/how-to-ingest-iot-hub-data .

When you write

@iotpnp(readonly)
, The property is generated as Property which's 'writable' value is false. On the IoT PnP side, this means that the Property is 'Device Twin Reported Property'.

You can write 'exclude' only,

@iotpnp(exclude) The propery is generared as Property only on Twin Graph side.

Command line to generate DTDL is as follows.

ConsoleAppDTDLGenerator.exe --metamodel BridgePoint\tools\mc\schema\sql\xtumlmc_schema.sql --base-datatype BridgePoint\tools\mc\schema\Globals.xtuml --domainmodel "BridgePoint\workspace<i>ADTTestModel\gen\code_generation<i>ADTTestModel.sql" --dtdlns dtmi:com:company --dtdlver 1 --use-keylett false --gen-folder "WorkingDir\dtdl"

3. Generate IoT Device Application from IoT PnP DTDL file.

By DTDL IoT App Generator, you can generate IoT Device Application C# code. Generated code has following features which are defined by IoT PnP DTDL file.

  • Connecting to IoT Hub.
  • Data structure for telemetry, desired properties and reported properties.
  • Send telemetry by repeat at regular intervals or on demand.
  • Receive handler for Direct Method invocation, cloud to device message and desired properties updating

Generated application uses https://github.com/kae-made/azure-iot-hub-device-app-framework as application framework. this framework provides common logic for IoT Device and IoT Edge implementation.

After generared application template, you need to add telemetry data preparetion logic into it.

Please see https://github.com/kae-made/dtdl-iot-app-generator/blob/main/HowToUse.md to know how to use this generator.

4. Generate Domain Model C# library

Using https://github.com/kae-made/domainmodel-code-generator-csharp, you can get Domain Model C# library code that consists from data structure and behavior whichi are defined in conceptual model. Command line to generate code set is

ConsoleAppCshaprGenerator.exe --metamodel BridgePoint\tools\mc\schema\sql\xtumlmc_schema.sql --base-datatype BridgePoint\tools\mc\schema\Globals.xtuml --domainmodel "BridgePoint\workspace<i>ADTTestModel\gen\code_generation<i>ADTTestModel.sql" --project ADTTestModel --dotnetver net6.0 --gen-folder "gen_folder" --action-gen true --adoptor-gen true --azuredigitaltwins dtmi:com:company;1 --azure-iot-hub true

Before generating, you'd better verify your conceptual model using BridgePoint's verifier. It is impossible to generate valid code from a model that does not correctly represent the real business world.
Generated code can be executed by https://github.com/kae-made/domain-model-csharp-adaptor-samples and should be verified not only by BridgePoint Verifier but also by this tool.
For your information, you can also use https://github.com/kae-made/domain-model-csharp-adaptor-samples/tree/main/UIDomainAdaptorSamples/WebAPIAppViewer published from same repository to deploy as Web Application.

Generated code uses https://github.com/kae-made/state-machine-framework and https://github.com/kae-made/charp-code-generation-framework as application framework.

5. Upload generated Twin Models

Upload the DTDL files generated in Step 2. to the Azure Digital Twins instance. You can use Azure Digital Twins Explorer or WpfAppDTDLParser.

6. Construct initial Twin Graph

Construct initial Twin Graph by Azure Digital Twins Explorer or WpfAppATDOperation.
It is very difficult to operate Twin Graph to maintain the constraints of property values and relationships defined in the conceptual model that it is recommended to construct Twin Graph state with the latter too or execute the generated Domain Model C# library.

7. Deploy and Setting Azure Services.

Please refer Microsoft Docs contents or "Azure の最新機能で IoT を改めてやってみる" for following work...