TypeEdge/README.md

# Azure IoT TypeEdge

The **Azure IoT TypeEdge** introduces a strongly typed flavor of the inherently loosely coupled vanilla [Azure IoT Edge](https:/azure.microsoft.com/en-us/services/iot-edge/).

Specifically:

- It removes all configuration burden from an IoT Edge application, because configuration can be now automatically generated by code reflection.
- Introduces compile time types checking across all modules
- It adds the ability to **emulate an IoT Edge device on the development environment**, by running all components in memory, no containers involved
- Simplifies the IoT Edge development down to an single F5 experience

## Development Environment Setup

<details>
  <summary>
  <b>Important:</b> If you just landed to this repo,<b> make sure you setup your environment first before continuing </b></summary>

To setup your development environment for **TypeEdge** you will need to:

 1. **Install [Docker](https://docs.docker.com/engine/installation/)** 
 2. **Install the latest [.NET Core](https://github.com/dotnet/core/blob/master/release-notes/download-archive.md)**
    > ***Important note***: **TypeEdge** requires **.NET Core 2.1.0-Preview2** and above, you can check your version by typing: 
    ```cmd
    dotnet --version
    ```
    > *As of 05/25/2018, the latest .NET Core release is [this](https://github.com/dotnet/core/blob/master/release-notes/download-archives/2.1.0-rc1-download.md)*

 1. **Install your favorite IDE ([VS Code](https://code.visualstudio.com/download) or [VS 2017](https://www.visualstudio.com/downloads/))**

    
1. **Temporary step - private NuGet packages**:
    
    Temporarily, and until GA, the required NuGet packages will be distributed through [this](https://msblox-03.pkgs.visualstudio.com/_packaging/private-nuget-feed/nuget/v3/index.json) private NuGet feed. After GA, these packages will be available in the www.nuget.org.
    
    > ***Important note:*** Only MS FTE have access to this NuGet feed. To add the feed to your machine wide configuration just once. This is required because of the way dotnet templates at the moment work.  
    
    To add the feed to your machine you will need your git credentials or a personal access token. TO get your git credentials, navigate to the [VSTS repo](https://msblox-03.visualstudio.com/csetypescript) and under **"clone to your computer"** section, click **"Generate Git Credentials"**

    Then, **add your credentials to the command bellow** and run it.

    ```
    nuget.exe sources Add -Name "private-typeedge-feed" -Source "https://msblox-03.pkgs.visualstudio.com/_packaging/private-nuget-feed/nuget/v3/index.json" -UserName USERNAME -Password PASSWORD
    ```
    You can download the latest nuget.exe from [here](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe)

    You'll also need to add the RocksDB ARM repo:
    ```
    nuget.exe sources Add -Name "RocksDB ARM" -Source "https://www.myget.org/F/rocksdb-native-arm/api/v3/index.json"
    ```
These steps will get you  ready to build your first TypeEdge application.

</details>
<br>

## QuickStart
Here is the quickest way to get started with TypeEdge. This quick start will create an IoT Edge solution with two modules and run it in the IoT Edge  emulator:

1. Install the TypeEdge .NET Core solution template. Just type:
    ```
    dotnet new -i TypeEdge.Application::*
    ```

    >**Note:** If you already installed the template and you want to **update to a newer template version**, you need to clear the dotnet http and template cache
    ```
    dotnet nuget locals http-cache --clear
    dotnet new --debug:reinit
    ```
2. Copy the **iothubowner connection string** from your development Azure **IoT Hub**.
    > The **iothubowner** is required because TypeEdge needs to provision a new device with the generated deployment configuration. 

1. Create a new IoT TypeEdge application:
    > You can choose the TypeEdge application and modules names of this template. In the example bellow, the application is called **Thermostat**, and the two modules are called **SensorModule** and **PreprocessorModule**. These names will be used as class names, so **Pascal casing** is suggested.
    ```
    dotnet new typeedgeapp -n Thermostat -m1 SensorModule -m2 PreprocessorModule -cs "YOUR_IOTHUBOWNER_CONNECTION"
    ```

1. Open in VS Code/Visual Studio 2017 and hit F5:

    ```
    cd Thermostat
    code .
    ```

    > Note: you can build and run with no IDE, simply by executing the following
    ```
    dotnet build Thermostat
    cd Thermostat\Thermostat.Emulator
    dotnet run
    ```


    > Note: You should now see the Edge Hub starting up.. 
![](images/IoTEdge.png) .. and the messages flowing in .. ![](images/messages.png)

**Congratulations!** You just created your first TypeEdge application. Continue reading bellow to learn how to deploy this application to an IoT Device

## How it works

**TypeEdge** for the moment only supports .NET Core C#. A **TypeEdge** application is a collection of **TypeEdge Modules**.

### Module interface

**TypeEdge** leverages **interfaces** to define the structure and behavior of the modules. A typical example of a **TypeEdge module definition** is:  
 ```cs
[TypeModule(Name = "SensorModule")]
public interface ISensorModule
{
    Output<SensorModuleOutput> Output { get; set; }
    ModuleTwin<SensorModuleTwin> Twin { get; set; }

    bool ResetModule(int sensorThreshold);
}
```

This module has a strongly typed output called ***Output*** and the messages type is ***SensorModuleOutput***. Similarly, it has a module twin called ***Twin*** with type ***SensorModuleTwin***
> Note: **TypeEdge** allows you to define multiple twin properties to enable partial twin updates

Finally, this module has a method that can be invoked directly with the bellow method signature:

```cs
bool ResetModule(int sensorThreshold);
```

### Module implementation

After describing the module behavior and structure with an interface, the next step is to implement this interface. This is effectively the code that will run in the **TypeEdge** module. Below is an implementation example of the above interface:

<details>
  <summary>Click to see the full <b>SensorModule</b> implementation code</summary>

```cs
public class SensorModule : EdgeModule, ISensorModule
{
    public Output<SensorModuleOutput> Output { get; set; }
    public ModuleTwin<SensorModuleTwin> Twin { get; set; }

    public bool ResetModule(int sensorThreshold)
    {
        System.Console.WriteLine($"New sensor threshold:{sensorThreshold}");
        return true;
    }

    public override async Task<ExecutionResult> RunAsync()
    {
        while (true)
        {
            await Output.PublishAsync(
                new SensorModuleOutput() {
                    Data = new System.Random().NextDouble().ToString() });
            
            System.Threading.Thread.Sleep(1000);
        }
        return await base.RunAsync();
    }
} 
```
</details>
<br>
A **TypeEdge** module can override any of the virtual methods of the base class ``EdgeModule``. As demonstrated in the above example, the ``RunAsync`` method is used for implementing long running loops, typically useful for modules that read sensor values. Another virtual method is ``Configure``, which can be used to read custom module configuration during startup. Finally, the ``BuildSubscriptions`` is used to define handlers to incoming messages.

The complete ``EdgeModule`` definition is:

```cs
public abstract class EdgeModule
{
    public EdgeModule();

    public virtual void BuildSubscriptions();
    public virtual CreationResult Configure(IConfigurationRoot configuration);
    public virtual Task<ExecutionResult> RunAsync();
}
```

### Module Subscriptions
**TypeEdge** uses the pub/sub pattern for all module I/O, except for the direct methods. This means that a module can subscribe to other module outputs, and publish messages to their inputs. To do this, a reference to the module interface definition is required. **TypeEdge** uses dependency injection to determine the referenced modules. 

Bellow, is the constructor of the second module included in the application template called ``PreprocessorModule``, that references the ``SensorModule`` via its interface.

```cs
public PreprocessorModule(ISensorModule proxy)
{
    this.proxy = proxy;
}
```

Using this proxy, the ``PreprocessorModule`` module can interact with the ``SensorModule``:
```cs
Input.Subscribe(proxy.Output, async (msg) =>
{
    await Output.PublishAsync(new PreprocessorModuleOutput()
    {
        Data = msg.Data,
        Metadata = System.DateTime.UtcNow.ToShortTimeString()
    });
    return MessageResult.OK;
});
```
In this example, the ``PreprocessorModule's`` input called ``Input``, subscribes to ``SensorModule's`` output, called ``Output``, and defines a subscription handler, a delegate that will be called every time the ``SensorModule`` sends a messages through its ``Output ``. In this example, the ``PreprocessorModule`` will enrich the incoming message, and publish it to its output called ``Output ``. These subscriptions need to be declared in the ``BuildSubscriptions`` override.

The complete code of the template's ``PreprocessorModule`` is:

<details>
  <summary>Click to see the full <b>PreprocessorModule</b> implementation code</summary>

```cs
public class PreprocessorModule : EdgeModule, IPreprocessorModule
{
    readonly ISensorModule proxy;

    public Output<PreprocessorModuleOutput> Output { get; set; }
    public Input<SensorModuleOutput> Input { get; set; }
    public ModuleTwin<PreprocessorModuleTwin> Twin { get; set; }

    public PreprocessorModule(ISensorModule proxy)
    {
        this.proxy = proxy;
    }

    public override void BuildSubscriptions()
    {
        Input.Subscribe(proxy.Output, async (msg) =>
        {
            await Output.PublishAsync(new PreprocessorModuleOutput()
            {
                Data = msg.Data,
                Metadata = System.DateTime.UtcNow.ToShortTimeString()
            });
            return MessageResult.OK;
        });
    }
}
```
</details>


### Emulator
The emulator references the Runtime bits achieve the emulation. Under the hood, the emulator starts a console application that hosts the Edge Hub  and all referenced modules. It will also provision a new Edge device to your designated IoT Hub (by the iothubowner connection string). This device will contain a fully functional deployment configuration, ready to be used to an actual device deployment.

To reference modules in an emulator application, both the interface and the implementation class of the module is required:

```cs
host.RegisterModule<ISensorModule, Modules.SensorModule>();
```

Finally, all subscriptions beyond to context of a single module can be defined here. For example: 
```cs
host.Upstream.Subscribe(host.GetProxy<IPreprocessorModule>().Output);
```

Below is the complete template emulator code for reference.


<details>
  <summary>Click to see the full <b>emulator</b> code</summary>

```cs
public static async Task Main(string[] args)
{
    //TODO: Set your IoT Hub iothubowner connection string in appsettings.json
    var configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .AddEnvironmentVariables()
        .AddCommandLine(args)
        .Build();

    var host = new TypeEdgeHost(configuration);

    //TODO: Register your TypeEdge Modules here
    host.RegisterModule<ISensorModule, Modules.SensorModule>();
    host.RegisterModule<IPreprocessorModule, Modules.PreprocessorModule>();

    //TODO: Define all cross-module subscriptions 
    host.Upstream.Subscribe(host.GetProxy<IPreprocessorModule>().Output);

    host.Build();

    await host.RunAsync();

    Console.WriteLine("Press <ENTER> to exit..");
    Console.ReadLine();
}
```

</details>

### Proxy
**TypeEdge**  adds functionality also for service application development (cloud side application). This template will create a Proxy project, useful for cloud side interaction with the TypeEdge application. It also leverages the interfaces as the way to create a strongly typed proxy client. The code to call a direct method of a TypeEdge module from the could side is literally one line:

```cs
ProxyFactory.GetModuleProxy<ISensorModule>().ResetModule(4);
```

### Solution structure
Apparently, to reference module definition interfaces and to avoid coupling the module implementation code together, these interfaces need to be defined in a separate project that will be commonly shared across the solution, containing only the definition interfaces and the referenced types.
![](images/solution.png)

## Device Deployment
[Coming soon]