Smdn.Net.SmartMeter.Extensions.Munin 2.1.0

Smdn.Net.SmartMeter.Extensions.Munin 2.1.0

Provides a mechanism for graphing data collected from low-voltage smart electric energy meter via route-B using Munin. More specifically, this library provides a SmartMeterMuninNode class that functions as a Munin node. This class enables Munin to collect and graph data aggregated from low-voltage smart electricity meters.

This library also provides a BackgroundService implementation that allows the Munin node implementation to run on any host environment.

「Bルート」を介して「低圧スマート電力量メータ」から収集したデータを、Muninによってグラフ化するための手段を提供します。 具体的には、このライブラリではMuninノードとして機能するSmartMeterMuninNodeクラスを提供します。 このクラスを使用することで、「低圧スマート電力量メータ」から収集したデータをMuninが集計・グラフ化できるようにします。

またこのライブラリでは、同Muninノードの実装を任意のホスト環境で動作させるためのBackgroundServiceの実装も提供します。

Usage

The following code shows an example of building a service to aggregate data from the smart meter and graph it using Munin.

以下のコードでは、スマートメーターからデータを収集し、Muninによってグラフ化するためのサービスを構築します。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;

using Polly;
using Polly.Telemetry;

using Smdn.Net.EchonetLite.RouteB.DependencyInjection;
using Smdn.Net.SmartMeter.MuninNode;
using Smdn.Net.SmartMeter.MuninNode.Hosting;

// スマートメーターからデータを収集し、Muninによってグラフ化するための
// アプリケーションを構築します。
var builder = Host.CreateApplicationBuilder(args);

// SmartMeterMuninNodeServiceを追加します。
// このサービスでは、Muninノードを動作させます。　このノードは、
// スマートメーターから定期的にデータを収集し、それをMuninプロトコルに
// よって取得・集計できるようにします。
builder.Services.AddHostedSmartMeterMuninNodeService(
  configureRouteBServices: routeBServices => {
    /*
     * Bルート・Wi-SUNデバイス・HEMSコントローラーの構成・設定を行います。
     *
     * 詳細な設定方法は、Smdn.Net.SmartMeterや
     * Smdn.Net.EchonetLite.RouteB.BP35XXのサンプルをご覧ください。
     *
     *   https://github.com/smdn/Smdn.Net.EchonetLite
     *   https://www.nuget.org/packages/Smdn.Net.SmartMeter
     *   https://www.nuget.org/packages/Smdn.Net.EchonetLite.RouteB.BP35XX
     */

    // Bルート通信を行うためのハンドラを追加します
    // routeBServices.AddRouteBHandler(...);

    // Bルート認証情報を追加します
    routeBServices.AddCredential(
      id: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // BルートID(ハイフン・スペースなし)を指定してください
      password: "XXXXXXXXXXXX" // Bルートパスワードを指定してください
    );

    // 必要に応じてタイムアウト・例外発生時のリトライおよび回復処理を設定します
    routeBServices
      .AddRetrySmartMeterConnectionTimeout(
        maxRetryAttempt: 10,
        delay: TimeSpan.FromSeconds(10)
      )
      .AddRetryDataAggregationTaskException(
        maxRetryAttempt: 10,
        delay: TimeSpan.FromSeconds(1),
        configureExceptionPredicates: predicateBuilder
          => predicateBuilder.Handle<TimeoutException>()
      );
  },
  configureMuninNodeOptions: muninNodeOptions => {
    /*
     * Muninノードの構成・設定を行います。
     *
     * 詳細な設定方法は、Smdn.Net.MuninNodeのサンプルをご覧ください。
     *
     *   https://github.com/smdn/Smdn.Net.MuninNode
     *   https://www.nuget.org/packages/Smdn.Net.MuninNode
     */
    muninNodeOptions.HostName = "smart-meter.munin-node.localhost";
    muninNodeOptions.UseAnyAddress();
  },
  configureSmartMeterMuninNode: muninNodeBuilder => {
    /*
     * 以下、動作させるMuninプラグインの構成・設定を行います。
     */

    // 瞬時電力計測値(W)を収集するMuninプラグインを追加します
    muninNodeBuilder.AddInstantaneousElectricPowerPlugin();

    // 瞬時電流計測値(A)を収集するMuninプラグインを追加します
    // このプラグインでは、R相・T相の計測値が同一のグラフに描画されます
    muninNodeBuilder.AddInstantaneousCurrentPlugin();

    // 定時積算電力量計測値(kWh)を収集するMuninプラグインを追加します
    // 必要に応じて、正方向・逆方向の計測値を収集・描画するかどうかを設定できます
    muninNodeBuilder.AddCumulativeElectricEnergyAtEvery30MinPlugin(
      enableNormalDirection: true,
      enableReverseDirection: false
    );

    // 毎日0時ちょうどの計測値をゼロ点とする、日間の定時積算電力量計測値(kWh)を
    // 収集するMuninプラグインを追加します
    muninNodeBuilder.AddDailyCumulativeElectricEnergyPlugin();

    // 毎週第1日の0時ちょうどの計測値をゼロ点とする、
    // 週間の定時積算電力量計測値(kWh)を収集するMuninプラグインを追加します
    // 週の開始日となる曜日は、任意に指定することができます
    muninNodeBuilder.AddWeeklyCumulativeElectricEnergyPlugin(
      firstDayOfWeek: DayOfWeek.Monday // 月曜日を週の初めとしてゼロ点・計測値を計算します
    );

    // 毎月1日の0時ちょうどの計測値をゼロ点とする、
    // 月間の定時積算電力量計測値(kWh)を収集するMuninプラグインを追加します
    muninNodeBuilder.AddMonthlyCumulativeElectricEnergyPlugin(
      enableNormalDirection: true,
      enableReverseDirection: false
    );
  }
);

// ログ出力を設定します
builder.Logging
  .AddSimpleConsole(static options => options.SingleLine = true)
  .AddFilter(typeof(SmartMeterMuninNode).FullName, LogLevel.Information)
  .AddFilter(static level => LogLevel.Warning <= level);

// Pollyからのログ出力を抑止するために、NullLoggerFactoryにリダイレクトします
builder.Services.Configure<TelemetryOptions>(
  configureOptions: static option => option.LoggerFactory = NullLoggerFactory.Instance
);

// ホストをビルドして起動します
using var host = builder.Build();

host.Run();

// systemdサービスなど、終了コードによってエラー時の動作を調整したい場合は、
// 以下のようにして終了コードを返すようにすることができます
// 以下のコードを使用するには、名前空間Smdn.Net.SmartMeter.MuninNode.Hosting.Systemdを
// インポートしてください
#if false
// まず、SmartMeterMuninNodeSystemdServiceを追加します
builder.Services.AddHostedSmartMeterMuninNodeSystemdService(...);

using var host = builder.Build();

// ホストを起動します
host.Run();

// 登録されているSmartMeterMuninNodeSystemdServiceを取得します
var mainService = host.Services.GetServices<IHostedService>().OfType<SmartMeterMuninNodeSystemdService>().First();

// SmartMeterMuninNodeSystemdServiceで終了コードが設定されている場合はその値を、
// そうでなければ0を終了コードとして返します
return mainService.ExitCode ?? 0;
#endif

The entire code is available on the GitHub repository.

完全なコードはGitHubリポジトリを参照してください。

Contributing

This project welcomes contributions, feedbacks and suggestions. You can contribute to this project by submitting Issues or Pull Requests on the GitHub repository.

API List

List of APIs exposed by assembly Smdn.Net.SmartMeter.Extensions.Munin-2.1.0 (net8.0)

// Smdn.Net.SmartMeter.Extensions.Munin.dll (Smdn.Net.SmartMeter.Extensions.Munin-2.1.0)
//   Name: Smdn.Net.SmartMeter.Extensions.Munin
//   AssemblyVersion: 2.1.0.0
//   InformationalVersion: 2.1.0+d6881059bda1389c20c3dc8eacfd375f4dd752fe
//   TargetFramework: .NETCoreApp,Version=v8.0
//   Configuration: Release
//   Referenced assemblies:
//     Microsoft.Extensions.DependencyInjection.Abstractions, Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60
//     Microsoft.Extensions.Hosting.Abstractions, Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60
//     Microsoft.Extensions.Logging.Abstractions, Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60
//     Smdn.Net.EchonetLite, Version=2.1.0.0, Culture=neutral
//     Smdn.Net.EchonetLite.RouteB, Version=2.1.0.0, Culture=neutral
//     Smdn.Net.EchonetLite.RouteB.Primitives, Version=2.1.0.0, Culture=neutral
//     Smdn.Net.MuninNode, Version=2.5.0.0, Culture=neutral
//     Smdn.Net.MuninNode.Hosting, Version=3.1.0.0, Culture=neutral
//     Smdn.Net.SmartMeter, Version=2.1.0.0, Culture=neutral
//     System.Collections, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.Collections.Concurrent, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.ComponentModel, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.Linq, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.Net.Primitives, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.Runtime, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
//     System.Threading, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
#nullable enable annotations

using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Net;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Smdn.Net.EchonetLite.RouteB;
using Smdn.Net.EchonetLite.RouteB.DependencyInjection;
using Smdn.Net.MuninNode;
using Smdn.Net.MuninNode.DependencyInjection;
using Smdn.Net.MuninNode.Hosting;
using Smdn.Net.MuninNode.Transport;
using Smdn.Net.MuninPlugin;
using Smdn.Net.SmartMeter;
using Smdn.Net.SmartMeter.MuninNode;
using Smdn.Net.SmartMeter.MuninNode.Hosting;
using Smdn.Net.SmartMeter.MuninNode.Hosting.Systemd;
using Smdn.Net.SmartMeter.MuninPlugin;

namespace Smdn.Net.MuninNode.DependencyInjection {
  public static class IMuninServiceBuilderExtensions {
    public static SmartMeterMuninNodeBuilder AddSmartMeterMuninNode(this IMuninServiceBuilder builder, Action<MuninNodeOptions> configureMuninNodeOptions, Action<IRouteBServiceBuilder<string>> configureRouteBServices) {}
  }
}

namespace Smdn.Net.SmartMeter.MuninNode {
  public sealed class SmartMeterMuninNode : LocalNode {
    public event EventHandler<Exception>? UnhandledAggregationException { add; remove; }

    public override string HostName { get; }
    public override IPluginProvider PluginProvider { get; }

    protected override void Dispose(bool disposing) {}
    protected override async ValueTask DisposeAsyncCore() {}
    protected override EndPoint GetLocalEndPointToBind() {}
    protected override ValueTask StartedAsync(CancellationToken cancellationToken) {}
    protected override async ValueTask StartingAsync(CancellationToken cancellationToken) {}
    protected override async ValueTask StoppedAsync(CancellationToken cancellationToken) {}
  }

  public sealed class SmartMeterMuninNodeBuilder : MuninNodeBuilder {
    protected override IMuninNode Build(IPluginProvider pluginProvider, IMuninNodeListenerFactory? listenerFactory, IServiceProvider serviceProvider) {}
  }

  public static class SmartMeterMuninNodeBuilderExtensions {
    public static SmartMeterMuninNodeBuilder AddCumulativeElectricEnergyAtEvery30MinPlugin(this SmartMeterMuninNodeBuilder builder, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddCumulativeElectricEnergyAtEvery30MinPlugin(this SmartMeterMuninNodeBuilder builder, string name, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddDailyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddDailyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, string name, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousCurrentPlugin(this SmartMeterMuninNodeBuilder builder, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousCurrentPlugin(this SmartMeterMuninNodeBuilder builder, TimeSpan aggregationInterval, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousCurrentPlugin(this SmartMeterMuninNodeBuilder builder, string name, TimeSpan aggregationInterval, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousElectricPowerPlugin(this SmartMeterMuninNodeBuilder builder, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousElectricPowerPlugin(this SmartMeterMuninNodeBuilder builder, TimeSpan aggregationInterval, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddInstantaneousElectricPowerPlugin(this SmartMeterMuninNodeBuilder builder, string name, TimeSpan aggregationInterval, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddMonthlyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddMonthlyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, string name, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddWeeklyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, DayOfWeek firstDayOfWeek = DayOfWeek.Sunday, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
    public static SmartMeterMuninNodeBuilder AddWeeklyCumulativeElectricEnergyPlugin(this SmartMeterMuninNodeBuilder builder, string name, DayOfWeek firstDayOfWeek = DayOfWeek.Sunday, bool enableNormalDirection = true, bool enableReverseDirection = false, Action<PluginGraphAttributesBuilder>? configureGraphAttributes = null) {}
  }
}

namespace Smdn.Net.SmartMeter.MuninNode.Hosting {
  public class AggregationHaltedException : InvalidOperationException {
    public AggregationHaltedException() {}
    public AggregationHaltedException(string message) {}
    public AggregationHaltedException(string message, Exception? innerException) {}
  }

  public static class IServiceCollectionExtensions {
    public static IServiceCollection AddHostedSmartMeterMuninNodeService(this IServiceCollection services, Action<IRouteBServiceBuilder<string>> configureRouteBServices, Action<MuninNodeOptions> configureMuninNodeOptions, Action<SmartMeterMuninNodeBuilder> configureSmartMeterMuninNode) {}
    public static IServiceCollection AddHostedSmartMeterMuninNodeService<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TSmartMeterMuninNodeService>(this IServiceCollection services, Action<IRouteBServiceBuilder<string>> configureRouteBServices, Action<MuninNodeOptions> configureMuninNodeOptions, Action<SmartMeterMuninNodeBuilder> configureSmartMeterMuninNode) where TSmartMeterMuninNodeService : SmartMeterMuninNodeService {}
  }

  public class SmartMeterMuninNodeService : MuninNodeBackgroundService {
    public SmartMeterMuninNodeService(SmartMeterMuninNode smartMeterMuninNode, ILogger<SmartMeterMuninNodeService>? logger = null) {}

    protected bool HasAggregationHalted { get; }

    public override void Dispose() {}
    protected override async Task ExecuteAsync(CancellationToken stoppingToken) {}
    protected virtual void OnAggregationHalted(Exception exception) {}
    protected bool TryGetAggregationFaultedException([NotNullWhen(true)] out Exception? unhandledAggregationException) {}
  }
}

namespace Smdn.Net.SmartMeter.MuninNode.Hosting.Systemd {
  public static class IServiceCollectionExtensions {
    public static IServiceCollection AddHostedSmartMeterMuninNodeSystemdService(this IServiceCollection services, Action<IRouteBServiceBuilder<string>> configureRouteBServices, Action<MuninNodeOptions> configureMuninNodeOptions, Action<SmartMeterMuninNodeBuilder> configureSmartMeterMuninNode) {}
    public static IServiceCollection AddHostedSmartMeterMuninNodeSystemdService<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TSmartMeterMuninNodeSystemdService>(this IServiceCollection services, Action<IRouteBServiceBuilder<string>> configureRouteBServices, Action<MuninNodeOptions> configureMuninNodeOptions, Action<SmartMeterMuninNodeBuilder> configureSmartMeterMuninNode) where TSmartMeterMuninNodeSystemdService : SmartMeterMuninNodeSystemdService {}
  }

  public class SmartMeterMuninNodeSystemdService : SmartMeterMuninNodeService {
    protected const int EX_TEMPFAIL = 75;
    protected const int EX_UNAVAILABLE = 69;

    public SmartMeterMuninNodeSystemdService(SmartMeterMuninNode smartMeterMuninNode, IHostApplicationLifetime applicationLifetime, ILogger<SmartMeterMuninNodeSystemdService>? logger = null) {}

    public int? ExitCode { get; }

    protected virtual bool DetermineExitCodeForUnhandledException(Exception exception, out int exitCode, [NotNullWhen(true)] out string? logMessage) {}
    protected override void OnAggregationHalted(Exception exception) {}
    public override async Task StartAsync(CancellationToken cancellationToken) {}
    public override async Task StopAsync(CancellationToken cancellationToken) {}
  }
}

namespace Smdn.Net.SmartMeter.MuninPlugin {
  public sealed class CumulativeElectricEnergyAtEvery30MinPlugin : PeriodicCumulativeElectricEnergyPlugin {
    public const string DefaultPluginName = "cumulative_electric_energy";

    public override TimeSpan DurationOfMeasurementPeriod { get; }
    public override DateTime StartOfMeasurementPeriod { get; }

    protected override bool TryGetBaselineValue(bool normalOrReverseDirection, out MeasurementValue<ElectricEnergyValue> @value) {}
  }

  public sealed class DailyCumulativeElectricEnergyPlugin : PeriodicCumulativeElectricEnergyPlugin {
    public const string DefaultPluginName = "cumulative_electric_energy_daily";

    public override TimeSpan DurationOfMeasurementPeriod { get; }
    public override DateTime StartOfMeasurementPeriod { get; }
  }

  public sealed class InstantaneousCurrentPlugin :
    InstantaneousCurrentAggregation,
    IPlugin,
    IPluginDataSource
  {
    public const string DefaultPluginName = "instantaneous_current";

    public IPluginDataSource DataSource { get; }
    public IReadOnlyCollection<IPluginField> Fields { get; }
    public IPluginGraphAttributes GraphAttributes { get; }
    public string Name { get; }
    public INodeSessionCallback? SessionCallback { get; }

    protected override void OnLatestValueUpdated() {}
  }

  public sealed class InstantaneousElectricPowerPlugin :
    InstantaneousElectricPowerAggregation,
    IPlugin,
    IPluginDataSource
  {
    public const string DefaultPluginName = "instantaneous_electric_power";

    public IPluginDataSource DataSource { get; }
    public IReadOnlyCollection<IPluginField> Fields { get; }
    public IPluginGraphAttributes GraphAttributes { get; }
    public string Name { get; }
    public INodeSessionCallback? SessionCallback { get; }

    protected override void OnLatestValueUpdated() {}
  }

  public sealed class MonthlyCumulativeElectricEnergyPlugin : PeriodicCumulativeElectricEnergyPlugin {
    public const string DefaultPluginName = "cumulative_electric_energy_monthly";

    public override TimeSpan DurationOfMeasurementPeriod { get; }
    public override DateTime StartOfMeasurementPeriod { get; }
  }

  public abstract class PeriodicCumulativeElectricEnergyPlugin :
    PeriodicCumulativeElectricEnergyAggregation,
    IPlugin,
    IPluginDataSource
  {
    public IPluginDataSource DataSource { get; }
    public IReadOnlyCollection<IPluginField> Fields { get; }
    public IPluginGraphAttributes GraphAttributes { get; }
    public string Name { get; }
    public INodeSessionCallback? SessionCallback { get; }

    protected override void OnNormalDirectionValueChanged() {}
    protected override void OnReverseDirectionValueChanged() {}
  }

  public sealed class WeeklyCumulativeElectricEnergyPlugin : PeriodicCumulativeElectricEnergyPlugin {
    public const string DefaultPluginName = "cumulative_electric_energy_weekly";

    public override TimeSpan DurationOfMeasurementPeriod { get; }
    public DayOfWeek FirstDayOfWeek { get; }
    public override DateTime StartOfMeasurementPeriod { get; }
  }
}
// API list generated by Smdn.Reflection.ReverseGenerating.ListApi.MSBuild.Tasks v1.6.0.0.
// Smdn.Reflection.ReverseGenerating.ListApi.Core v1.4.0.0 (https://github.com/smdn/Smdn.Reflection.ReverseGenerating)