Skip to content

Commit

Permalink
Merge pull request #15 from lillo42/improve-docs
Browse files Browse the repository at this point in the history
Improve docs and add sample
  • Loading branch information
lillo42 authored Feb 12, 2020
2 parents 3005598 + 9b8bc9c commit 2fc597a
Show file tree
Hide file tree
Showing 11 changed files with 321 additions and 94 deletions.
3 changes: 1 addition & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -329,5 +329,4 @@ ASALocalRun/

# MFractors (Xamarin productivity tool) working folder
.mfractor/

.DS_Store
.DS_Store
25 changes: 20 additions & 5 deletions Mozzila.IoT.WebThing.sln
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,18 @@ EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "sample", "sample", "{370B1F76-EFE0-44D4-A395-59F5EF266112}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Itens", "Solution Itens", "{E90FFA85-A210-450A-AA08-528D7F8962C2}"
ProjectSection(SolutionItems) = preProject
Directory.Build.props = Directory.Build.props
.editorconfig = .editorconfig
azure-pipelines.yml = azure-pipelines.yml
EndProjectSection
ProjectSection(SolutionItems) = preProject
Directory.Build.props = Directory.Build.props
.editorconfig = .editorconfig
README.md = README.md
EndProjectSection
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleThing", "sample\SampleThing\SampleThing.csproj", "{6FB673AA-FD52-4509-97C8-28572549F609}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Mozilla.IoT.WebThing.AcceptanceTest", "test\Mozilla.IoT.WebThing.AcceptanceTest\Mozilla.IoT.WebThing.AcceptanceTest.csproj", "{0D709627-98FA-4A39-8631-90C982ADED44}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MultiThing", "sample\MultiThing\MultiThing.csproj", "{3CDFC9FB-F240-419A-800D-79C506CBDAE2}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down Expand Up @@ -85,11 +87,24 @@ Global
{0D709627-98FA-4A39-8631-90C982ADED44}.Release|x64.Build.0 = Release|Any CPU
{0D709627-98FA-4A39-8631-90C982ADED44}.Release|x86.ActiveCfg = Release|Any CPU
{0D709627-98FA-4A39-8631-90C982ADED44}.Release|x86.Build.0 = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|Any CPU.Build.0 = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|x64.ActiveCfg = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|x64.Build.0 = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|x86.ActiveCfg = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Debug|x86.Build.0 = Debug|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|Any CPU.ActiveCfg = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|Any CPU.Build.0 = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|x64.ActiveCfg = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|x64.Build.0 = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|x86.ActiveCfg = Release|Any CPU
{3CDFC9FB-F240-419A-800D-79C506CBDAE2}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(NestedProjects) = preSolution
{4999C9EF-BCC2-4252-A404-0161E655AAD9} = {F6436C38-AB0A-4D3F-8BA7-E2C0FA30D052}
{63874B3F-6000-418D-BD19-C56A4D86B612} = {65C51E32-2901-4983-A238-0F931D9EB651}
{6FB673AA-FD52-4509-97C8-28572549F609} = {370B1F76-EFE0-44D4-A395-59F5EF266112}
{0D709627-98FA-4A39-8631-90C982ADED44} = {65C51E32-2901-4983-A238-0F931D9EB651}
{3CDFC9FB-F240-419A-800D-79C506CBDAE2} = {370B1F76-EFE0-44D4-A395-59F5EF266112}
EndGlobalSection
EndGlobal
123 changes: 61 additions & 62 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# webthing

![Build](https://github.com/lillo42/webthing-csharp/workflows/Build/badge.svg)
[![NuGet](http://img.shields.io/nuget/v/Mozilla.IoT.WebThing.svg)](https://www.nuget.org/packages/Mozilla.IoT.WebThing/)



Implementation of an HTTP [Web Thing](https://iot.mozilla.org/wot/).

# Using
Expand Down Expand Up @@ -27,57 +32,51 @@ Imagine you have a dimmable light that you want to expose via the web of things
First we create a new Thing:

```csharp
var light = new Thing
public class LampThing : Thing
{
Name = "My Lamp",
Type = new [] { "OnOffSwitch", "Light" },
Description = "A web connected lamp"
};
public override string Name => "my-lamp-123";
public override string? Title => "My Lamp";
public override string? Description => "A web connected lamp";
public override string[]? Type { get; } = new[] { "Light", "OnOffSwitch" };

}
```

Now we can add the required properties.

The **`on`** property reports and sets the on/off state of the light. For this, we need to have a `Property` object which holds the actual state and also a method to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.
The **`on`** property reports and sets the on/off state of the light. For this, we need to create a new property in Thing. For our purposes, we just want to log the new state if the light is switched on/off.

```csharp
var onDescription = new Dictionary<string, object>
public class LampThing : Thing
{
["@type"] = "OnOffProperty",
["title"] = "On/Off",
["type"] = "boolean",
["description"] = "Whether the lamp is turned on"
};

var property = new Property<bool>(light, "on", true, onDescription);
property.ValuedChanged += (sender, value) =>
{
Console.WriteLine($"On-State is now {value}");
};

light.AddProperty(property);
...
[ThingProperty(Type = new []{ "OnOffProperty" }, Title = "On/Off",
Description = "Whether the lamp is turned on")]
public bool On { get; set; }
}
```

The **`brightness`** property reports the brightness level of the light and sets the level. Like before, instead of actually setting the level of a light, we just log the level.

```csharp
var brightnessDescription = new Dictionary<string, object>
public class LampThing : Thing
{
["@type"] = "BrightnessProperty",
["title"] = "Brightness",
["type"] = "integer",
["description"] = "The level of light from 0-100",
["minimum"] = 0,
["maximum"] = 100,
["unit"] = "percent"
};

var level = new Property<double>(light, "level", true, onDescription);
level.ValuedChanged += (sender, value) =>
{
Console.WriteLine($"Brightness is now {value}");
};

light.AddProperty(level);
...

private int _brightness;
[ThingProperty(Type = new []{ "BrightnessProperty" },Title = "Brightness",
Description = "The level of light from 0-100", Minimum = 0, Maximum = 100,
Unit = "percent")]
public int Brightness
{
get => _brightness;
set
{
_brightness = value;
Console.WriteLine($"Brightness is now {value}");
}
}
}
```

Now we can add our newly created thing and add Thing middleware to Asp Net Core:
Expand All @@ -86,13 +85,15 @@ Now we can add our newly created thing and add Thing middleware to Asp Net Core:
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddThing(option => option.IsSingleThing = true);
services.AddThings()
.AddThing<LampThing>();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseEndpoints(config => {
config.MapThing(light);
app.UseEndpoints(endpoints =>
{
endpoints.MapThings();
});
}
```
Expand All @@ -108,33 +109,29 @@ A [`MultiLevelSensor`](https://iot.mozilla.org/schemas/#MultiLevelSensor) (a sen
First we create a new Thing:

```csharp
var sensor = new Thing
public class Humidity : Thing
{
Name = "My Humidity Sensor",
Type = new [] { "MultiLevelSensor" },
Description = "A web connected humidity sensor"
};
public override string? Title => "My Humidity Sensor";

public override string[]? Type { get; } = new[] {"MultiLevelSensor"};

public override string? Description => "A web connected humidity sensor";
}
```

Then we create and add the appropriate property:
* `level`: tells us what the sensor is actually reading
* Contrary to the light, the value cannot be set via an API call, as it wouldn't make much sense, to SET what a sensor is reading. Therefore, we are creating a *readOnly* property.

```csharp
var levelDescription = new Dictionary<string, object>
{
["@type"] = "LevelProperty",
["title"] = "Humidity",
["type"] = "number",
["description"] = "The current humidity in %",
["minimum"] = 0,
["maximum"] = 100,
["unit"] = "percent",
["readOnly"] = true
};

sensor.AddProperty(new Property<double>(sensor, "level", 0, levelDescription));
```
```csharp
public class Humidity : Thing
{
...
[ThingProperty(Type = new []{"LevelProperty"}, Title = "Humidity", Description = "The current humidity in %",
Minimum = 0, Maximum = 100, Unit = "percent")]
public double Level { get; private set; }
}
```

Now we have a sensor that constantly reports 0%. To make it usable, we need a thread or some kind of inAdd when the sensor has a new reading available. For this purpose we start a task that queries the physical sensor every few seconds. For our purposes, it just calls a fake method.

Expand All @@ -143,8 +140,10 @@ Now we have a sensor that constantly reports 0%. To make it usable, we need a th
Task.Factory.StartNew(async () => {
await Task.Delay(3_000);
await level.NotifyOfExternalUpdate(ReadFromGPIO());
await Level = ReadFromGPIO();
});
```

This will update our `Value` object with the sensor readings via the `this.level.NotifyOfExternalUpdate(ReadFromGPIO());` call. The `Value` object now notifies the property and the thing that the value has changed, which in turn notifies all websocket listeners.
## Limitation

Current version, 2.0.0-previewX, Websocket is not working
12 changes: 12 additions & 0 deletions sample/MultiThing/MultiThing.csproj
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

<ItemGroup>
<ProjectReference Include="..\..\src\Mozilla.IoT.WebThing\Mozilla.IoT.WebThing.csproj" />
</ItemGroup>


</Project>
26 changes: 26 additions & 0 deletions sample/MultiThing/Program.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace MultiThing
{
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}
51 changes: 51 additions & 0 deletions sample/MultiThing/Startup.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using MultiThing.Things;

namespace MultiThing
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddThings()
.AddThing<ExampleDimmableLight>()
.AddThing<FakeGpioHumiditySensor>();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapThings();
});
}
}
}
Loading

0 comments on commit 2fc597a

Please sign in to comment.