diff --git a/NucuCar.Domain/Guard.cs b/NucuCar.Domain/Guard.cs index 10bfa75..009ddad 100644 --- a/NucuCar.Domain/Guard.cs +++ b/NucuCar.Domain/Guard.cs @@ -1,10 +1,18 @@ using System; -using Microsoft.Extensions.Logging; namespace NucuCar.Domain { + /// + /// Helper class used for checking arguments and raise exception if the checks don't pass. + /// public static class Guard { + /// + /// Checks if the argument string is null or whitespace and raises exception on check fail. + /// + /// The argument name that will be logged in the exception message. + /// The argument to check if it's null or whitespace. + /// Raised if the argument is null or whitespace. internal static void ArgumentNotNullOrWhiteSpace(string argumentName, string argument) { if (string.IsNullOrWhiteSpace(argument)) @@ -13,6 +21,12 @@ namespace NucuCar.Domain } } + /// + /// Checks if the argument is null and raises exception on check fail. + /// + /// The argument name that will be logged in the exception message. + /// The argument to check if it's null. + /// Raised if the argument is null. public static void ArgumentNotNull(string argumentName, object argument) { if (argument == null) diff --git a/NucuCar.Domain/Telemetry/ITelemeter.cs b/NucuCar.Domain/Telemetry/ITelemeter.cs index 292232c..5ecae45 100644 --- a/NucuCar.Domain/Telemetry/ITelemeter.cs +++ b/NucuCar.Domain/Telemetry/ITelemeter.cs @@ -2,10 +2,22 @@ using System.Collections.Generic; namespace NucuCar.Domain.Telemetry { + /// + /// Interface that specifies that the component implementing it is willing to provide telemetry data and can be + /// registered to a publisher such as . + /// public interface ITelemeter { + /// + /// This function should return an identifier that identifies the component providing the telemetry data. + /// + /// An identifier for the telemetry source. string GetIdentifier(); - /* Dictionary containing the topic and the value */ + + /// + /// This function should return a dictionary containing the telemetry data. + /// + /// The telemetry data. It should be JSON serializable. Dictionary GetTelemetryData(); } } \ No newline at end of file diff --git a/NucuCar.Domain/Telemetry/TelemetryPublisher.cs b/NucuCar.Domain/Telemetry/TelemetryPublisher.cs index 218ff57..0acbfb4 100644 --- a/NucuCar.Domain/Telemetry/TelemetryPublisher.cs +++ b/NucuCar.Domain/Telemetry/TelemetryPublisher.cs @@ -6,14 +6,36 @@ using Microsoft.Extensions.Logging; namespace NucuCar.Domain.Telemetry { + /// + /// The TelemetryPublisher is an abstract class, which provides a base for implementing telemetry publishers. + /// public abstract class TelemetryPublisher : IDisposable { + /// + /// Raw connection string that is used to connect to the cloud service. Should be parsed if required. + /// protected string ConnectionString { get; set; } + + /// + /// Telemetry source that indicates the source of the telemetry data. + /// protected string TelemetrySource { get; set; } + + /// + /// A list containing entries to the telemeters that want to publish data to the cloud. + /// protected readonly List RegisteredTelemeters; + + /// + /// The logging instance, if it's null then the module won't log anything. + /// // ReSharper disable once UnassignedField.Global protected readonly ILogger Logger; + /// + /// Constructor for . + /// + /// TelemetryPublisher options, see: protected TelemetryPublisher(TelemetryPublisherBuilderOptions opts) { ConnectionString = opts.ConnectionString; @@ -22,22 +44,42 @@ namespace NucuCar.Domain.Telemetry RegisteredTelemeters = new List(5); } + /// + /// Method that sends all data from the () to the cloud. + /// + /// A cancellation token. + /// A task public abstract Task PublishAsync(CancellationToken cancellationToken); + + /// + /// Method that releases all managed resources. + /// + public abstract void Dispose(); + + + /// + /// Method that adds a telemeter to the collection. + /// The telemeter can register only once. + /// + /// The + /// Returns true if the telemeter has registered successfully and false otherwise. public bool RegisterTelemeter(ITelemeter t) { if (RegisteredTelemeters.Contains(t)) return false; RegisteredTelemeters.Add(t); return true; - } + /// + /// Method that deletes a telemeter from the collection. + /// + /// The + /// Returns true if the telemeter has unregistered successfully and false otherwise. public bool UnRegisterTelemeter(ITelemeter t) { if (!RegisteredTelemeters.Contains(t)) return false; RegisteredTelemeters.Remove(t); return true; } - - public abstract void Dispose(); } } \ No newline at end of file diff --git a/NucuCar.Domain/Telemetry/TelemetryPublisherAzure.cs b/NucuCar.Domain/Telemetry/TelemetryPublisherAzure.cs index d8b0419..554f772 100644 --- a/NucuCar.Domain/Telemetry/TelemetryPublisherAzure.cs +++ b/NucuCar.Domain/Telemetry/TelemetryPublisherAzure.cs @@ -28,13 +28,24 @@ namespace NucuCar.Domain.Telemetry Logger?.LogInformation("Started the AzureTelemetryPublisher!"); } + /// + /// Creates an instance of that is used to publish data to Microsoft Azure. + /// + /// The device connection string for Microsoft Azure IoT hub device. + /// A instance. public static TelemetryPublisher CreateFromConnectionString(string connectionString) { Guard.ArgumentNotNullOrWhiteSpace(nameof(connectionString), connectionString); return new TelemetryPublisherAzure(new TelemetryPublisherBuilderOptions() {ConnectionString = connectionString, TelemetrySource = "TelemetryPublisherAzure"}); } - + + /// + /// Creates an instance of that is used to publish data to Microsoft Azure. + /// + /// Device connection string for Microsoft Azure IoT hub device. + /// String that is used to identify the source of the telemetry data. + /// A instance. public static TelemetryPublisher CreateFromConnectionString(string connectionString, string telemetrySource) { @@ -43,7 +54,14 @@ namespace NucuCar.Domain.Telemetry return new TelemetryPublisherAzure(new TelemetryPublisherBuilderOptions() {ConnectionString = connectionString, TelemetrySource = telemetrySource}); } - + + /// + /// Creates an instance of that is used to publish data to Microsoft Azure. + /// + /// Device connection string for Microsoft Azure IoT hub device. + /// String that is used to identify the source of the telemetry data. + /// An logger instance. + /// A instance. public static TelemetryPublisher CreateFromConnectionString(string connectionString, string telemetrySource, ILogger logger) { diff --git a/NucuCar.Domain/Telemetry/TelemetryPublisherBuilderOptions.cs b/NucuCar.Domain/Telemetry/TelemetryPublisherBuilderOptions.cs index dabac27..9411218 100644 --- a/NucuCar.Domain/Telemetry/TelemetryPublisherBuilderOptions.cs +++ b/NucuCar.Domain/Telemetry/TelemetryPublisherBuilderOptions.cs @@ -2,10 +2,24 @@ using Microsoft.Extensions.Logging; namespace NucuCar.Domain.Telemetry { + /// + /// This class contains options for the . + /// public class TelemetryPublisherBuilderOptions { + /// + /// The ConnectionString used by the publisher to connect to the cloud service. + /// public string ConnectionString { get; set; } + + /// + /// A string that indicates the source of the telemetry data. + /// public string TelemetrySource { get; set; } + + /// + /// The logger instance. + /// public ILogger Logger { get; set; } } } \ No newline at end of file diff --git a/NucuCar.Sensors/EnvironmentSensor/BackgroundWorker.cs b/NucuCar.Sensors/EnvironmentSensor/BackgroundWorker.cs index bf558ec..202f718 100644 --- a/NucuCar.Sensors/EnvironmentSensor/BackgroundWorker.cs +++ b/NucuCar.Sensors/EnvironmentSensor/BackgroundWorker.cs @@ -8,6 +8,10 @@ using NucuCarSensorsProto; namespace NucuCar.Sensors.EnvironmentSensor { + /// + /// EnvironmentSensor's background service worker. + /// It does periodic reads from the sensors and publishes telemetry data if the option is enabled. + /// public class BackgroundWorker : BackgroundService { private readonly bool _serviceEnabled; @@ -54,7 +58,7 @@ namespace NucuCar.Sensors.EnvironmentSensor await Task.Delay(_measurementDelay, stoppingToken); } - + SensorTelemetryPublisher.Instance.UnRegisterTelemeter(sensor); } } diff --git a/NucuCar.Sensors/EnvironmentSensor/Bme680Sensor.cs b/NucuCar.Sensors/EnvironmentSensor/Bme680Sensor.cs index 0c103fe..d0722e8 100644 --- a/NucuCar.Sensors/EnvironmentSensor/Bme680Sensor.cs +++ b/NucuCar.Sensors/EnvironmentSensor/Bme680Sensor.cs @@ -10,6 +10,10 @@ using NucuCarSensorsProto; namespace NucuCar.Sensors.EnvironmentSensor { + /// + /// Abstraction for the BME680 sensor. + /// See: https://www.bosch-sensortec.com/bst/products/all_products/bme680 + /// public class Bme680Sensor : IDisposable, ITelemeter { public ILogger Logger; @@ -117,6 +121,7 @@ namespace NucuCar.Sensors.EnvironmentSensor ["voc"] = _lastMeasurement.VolatileOrganicCompound }; } + return returnValue; } } diff --git a/NucuCar.Sensors/EnvironmentSensor/GrpcService.cs b/NucuCar.Sensors/EnvironmentSensor/GrpcService.cs index c5f6a11..2629288 100644 --- a/NucuCar.Sensors/EnvironmentSensor/GrpcService.cs +++ b/NucuCar.Sensors/EnvironmentSensor/GrpcService.cs @@ -6,6 +6,10 @@ using NucuCarSensorsProto; namespace NucuCar.Sensors.EnvironmentSensor { + /// + /// EnvironmentSensor's gRPC service. + /// It allows reading the sensor's data using remote procedure calls. + /// public class GrpcService : EnvironmentSensorGrpcService.EnvironmentSensorGrpcServiceBase { private readonly ILogger _logger; @@ -26,7 +30,8 @@ namespace NucuCar.Sensors.EnvironmentSensor }); } - public override Task GetSensorMeasurement(Empty request, ServerCallContext context) + public override Task GetSensorMeasurement(Empty request, + ServerCallContext context) { _logger?.LogDebug($"Calling {nameof(GetSensorMeasurement)}."); var sensorMeasurement = _bme680Sensor.GetMeasurement(); diff --git a/NucuCar.Sensors/GrpcStartup.cs b/NucuCar.Sensors/GrpcStartup.cs index 1fffdea..aaf5246 100644 --- a/NucuCar.Sensors/GrpcStartup.cs +++ b/NucuCar.Sensors/GrpcStartup.cs @@ -25,9 +25,10 @@ namespace NucuCar.Sensors app.UseRouting(); app.UseHttpsRedirection(); - + app.UseEndpoints(endpoints => { + // Add the gRPC services here. endpoints.MapGrpcService(); endpoints.MapGet("/", diff --git a/NucuCar.Sensors/Telemetry/BackgroundWorker.cs b/NucuCar.Sensors/Telemetry/BackgroundWorker.cs index eb16980..a5cd7d7 100644 --- a/NucuCar.Sensors/Telemetry/BackgroundWorker.cs +++ b/NucuCar.Sensors/Telemetry/BackgroundWorker.cs @@ -6,6 +6,9 @@ using Microsoft.Extensions.Logging; namespace NucuCar.Sensors.Telemetry { + /// + /// Telemetry service, which pools the telemetry sources and pushes telemetry data to the cloud. + /// public class BackgroundWorker : BackgroundService { private readonly bool _serviceEnabled; diff --git a/NucuCar.Sensors/Telemetry/SensorTelemetryPublisher.cs b/NucuCar.Sensors/Telemetry/SensorTelemetryPublisher.cs index 455d2bb..8f3e553 100644 --- a/NucuCar.Sensors/Telemetry/SensorTelemetryPublisher.cs +++ b/NucuCar.Sensors/Telemetry/SensorTelemetryPublisher.cs @@ -9,20 +9,20 @@ namespace NucuCar.Sensors.Telemetry private static object _palock = new object(); public static TelemetryPublisher Instance { get; private set; } + /// + /// Creates a telemetry publisher instance see . + /// public static TelemetryPublisher CreateSingleton(string connectionString, string telemetrySource, ILogger logger) { - if (Instance == null) + lock (_palock) { - lock (_palock) - { - var telemetryPublisher = - TelemetryPublisherAzure.CreateFromConnectionString(connectionString, telemetrySource, logger); - Instance = telemetryPublisher; - } + if (Instance != null) return Instance; + var telemetryPublisher = + TelemetryPublisherAzure.CreateFromConnectionString(connectionString, telemetrySource, logger); + Instance = telemetryPublisher; + return Instance; } - - return Instance; } private static void ReleaseUnmanagedResources() diff --git a/Readme.md b/Readme.md index 6553036..38aaff7 100644 --- a/Readme.md +++ b/Readme.md @@ -32,7 +32,7 @@ dotnet build --runtime linux-arm -p:PublishSingleFile=true - [X] Make a working BME680 module. ~~(Unit tests?)~~ - [X] Add settings: ~~gRPC enabled~~, Telemetry Enabled, Sensor Enabled, Measurement Delay - [X] Make a gRPC test project to test the modules. -- [ ] Pretty document domain module. +- [X] Pretty document domain module. - [ ] Attempt some unit tests on sensors. - [ ] Grpc - [ ] Telemetry