v2c-any 0.1.9 → 0.2.1

package/README.md

@@ -40,7 +40,7 @@ It adapts **any input** into the protocol and format expected by a V2C wallbox
 
 Or in practical terms:
 
-```
+```text
 [Any Meter | MQTT | API | Simulator]
             │
             ▼
@@ -129,6 +129,7 @@ docker run -v $(pwd)/.v2carc.yaml:/app/.v2carc.yaml v2c-any
 Emulates a **Shelly Pro EM** energy meter by exposing a REST API that V2C wallboxes can poll.
 
 **Use this when:**
+
 - Your V2C wallbox is configured to poll a Shelly meter
 - You want to act as a drop-in replacement for physical hardware
 - You prefer a pull-based (polling) approach
@@ -139,12 +140,12 @@ Emulates a **Shelly Pro EM** energy meter by exposing a REST API that V2C wallbo
 provider: rest
 properties:
   port: 3000
-  device: shelly-pro-em
   meters:
     grid:
       feed:
         type: adapter
         properties:
+          device: shelly-pro-em
           ip: 192.168.1.100
     solar:
       feed:
@@ -162,6 +163,7 @@ properties:
 ```
 
 **How it works:**
+
 1. `v2ca` starts a Fastify HTTP server
 2. Exposes endpoints matching Shelly Pro EM API format
 3. V2C wallbox polls these endpoints (e.g., `/rpc/EM1.GetStatus?id=0`)
@@ -172,6 +174,7 @@ properties:
 Publishes power data directly to MQTT topics that V2C wallboxes subscribe to.
 
 **Use this when:**
+
 - Your V2C wallbox is configured for MQTT integration
 - You have an existing MQTT broker
 - You want push-based (event-driven) updates
@@ -183,13 +186,13 @@ Publishes power data directly to MQTT topics that V2C wallboxes subscribe to.
 provider: mqtt
 properties:
   url: mqtt://broker.local:1883
-  device: shelly-pro-em
   meters:
     grid:
       mode: pull       # v2ca polls your device
       feed:
         type: adapter
         properties:
+          device: shelly-pro-em
           interval: 2000   # Every 2 seconds
           ip: 192.168.1.100
     solar:
@@ -202,6 +205,7 @@ properties:
 ```
 
 **How it works:**
+
 1. `v2ca` connects to your MQTT broker
 2. Publishes to V2C-expected topics (e.g., `trydan_v2c_sun_power`)
 3. Supports both **pull** (polling devices) and **push** (subscribing to topics)

package/dist/device/shelly-pro-em/em1-status-provider.js

@@ -1,6 +1,10 @@
-import { request } from 'undici';
+import { Client, interceptors } from 'undici';
 import { logger } from '../../utils/logger.js';
 import { energyTypeToId } from '../../utils/mappers.js';
+import { AsymmetricEMAProvider } from '../../provider/asymmetric-emea-provider.js';
+import { RetryableProvider } from '../../provider/retryable-provider.js';
+import { em1StatusInterpolator } from '../../utils/interpolator.js';
+import { DecoratorProviderFactory } from '../../factory/decorator-provider-factory.js';
 /**
  * Provider that fetches EM1 status data from a Shelly Pro EM device via HTTP.
  * Retrieves real-time energy monitoring data by querying the device's RPC API endpoint.
@@ -14,6 +18,9 @@ export class EM1StatusProvider {
     constructor(host, energyType) {
         this.host = host;
         this.energyType = energyType;
+        const { responseError } = interceptors;
+        this.client = new Client(`http://${this.host}`).compose(responseError());
+        this.id = energyTypeToId(energyType);
     }
     /**
      * Fetches the current EM1 status from the device.
@@ -22,8 +29,10 @@ export class EM1StatusProvider {
      */
     async get() {
         logger.debug({ host: this.host, energyType: this.energyType }, 'Fetching EM1Status');
-        const id = energyTypeToId(this.energyType);
-        const res = await request(`http://${this.host}/rpc/EM1.GetStatus?id=${id}`, { method: 'GET' });
+        const res = await this.client.request({
+            path: `/rpc/EM1.GetStatus?id=${this.id}`,
+            method: 'GET',
+        });
         return (await res.body.json());
     }
 }
@@ -46,4 +55,13 @@ class EM1StatusProviderFactory {
  * Singleton factory instance for creating `EM1StatusProvider` objects.
  * Provides a ready-to-use factory to build providers with supplied options.
  */
-export const em1StatusProviderFactory = new EM1StatusProviderFactory();
+const localEm1StatusProviderFactory = new EM1StatusProviderFactory();
+export const em1StatusProviderFactory = new DecoratorProviderFactory(localEm1StatusProviderFactory, (provider) => new AsymmetricEMAProvider(new RetryableProvider(provider, { retries: 3 }), em1StatusInterpolator, {
+    alphaRise: 1,
+    alphaFall: 0.2,
+    comparator: (a, b) => {
+        const powerA = a?.act_power ?? 0;
+        const powerB = b?.act_power ?? 0;
+        return powerA - powerB;
+    },
+}));

package/dist/factory/decorator-provider-factory.js

@@ -0,0 +1,40 @@
+/**
+ * Generic factory that wraps another provider factory with a decorator pattern.
+ * Enables composition by allowing providers to be enhanced with additional behavior
+ * such as retry logic, caching, logging, validation, etc.
+ *
+ * This factory creates providers by first using the wrapped factory to create a base provider,
+ * then applying a decorator function to enhance it with additional capabilities.
+ *
+ * @example
+ * // Creating a provider factory with retry capability
+ * const retryDecorator = (provider) => new RetryableProvider(provider, { retries: 3 });
+ * const resilientFactory = new DecoratorProviderFactory(baseFactory, retryDecorator);
+ * const resilientProvider = resilientFactory.create(options);
+ *
+ * @template Options - The configuration options type required by the wrapped factory
+ * @template T - The type of data the created providers will supply
+ */
+export class DecoratorProviderFactory {
+    /**
+     * Creates a new decorator provider factory.
+     * @param providerFactory - The underlying factory that creates base providers
+     * @param decorator - Function that enhances providers with additional behavior
+     */
+    constructor(providerFactory, decorator) {
+        this.providerFactory = providerFactory;
+        this.decorator = decorator;
+    }
+    /**
+     * Creates a decorated provider using the wrapped factory and decorator function.
+     * First creates a base provider using the wrapped factory, then applies the decorator
+     * to enhance it with additional capabilities.
+     *
+     * @param options - Configuration options for the wrapped provider factory
+     * @returns A decorated provider with enhanced behavior
+     */
+    create(options) {
+        const baseProvider = this.providerFactory.create(options);
+        return this.decorator(baseProvider);
+    }
+}

package/dist/factory/em1-status-provider-factory.js

@@ -6,10 +6,10 @@ import { FixedValueProviderFactory } from '../provider/fixed-value-provider.js';
 export class EM1StatusProviderFactory {
     /**
      * Creates a new EM1Status provider factory.
-     * @param devicesProvider - Registry containing provider factories for different devices
+     * @param providerFactoryRegistry - Registry containing provider factories for different devices
      */
-    constructor(devicesProvider) {
-        this.devicesProvider = devicesProvider;
+    constructor(providerFactoryRegistry) {
+        this.providerFactoryRegistry = providerFactoryRegistry;
     }
     /**
      * Creates the appropriate provider factory based on the feed configuration type.
@@ -20,11 +20,12 @@ export class EM1StatusProviderFactory {
     createProviderFactory(options) {
         switch (options.configuration.feed.type) {
             case 'adapter': {
-                const provider = this.devicesProvider.get(options.device);
-                if (!provider) {
-                    throw new Error(`No provider registered for device: ${options.device}`);
+                const device = options.configuration.feed.properties.device;
+                const providerFactory = this.providerFactoryRegistry.get(device);
+                if (!providerFactory) {
+                    throw new Error(`No provider registered for device: ${device}`);
                 }
-                return provider;
+                return providerFactory;
             }
             case 'mock':
                 return new FixedValueProviderFactory({

package/dist/factory/mqtt-feed-executable-service-factory.js

@@ -52,14 +52,12 @@ export class MqttFeedExecutableServiceFactory {
             case 'pull':
                 return this.pullExecutableServiceFactory.create({
                     energyType: options.energyType,
-                    device: options.device,
                     configuration: options.configuration.feed,
                     callbackProperties,
                 });
             case 'push':
                 return this.pushExecutableServiceFactory.create({
                     energyType: options.energyType,
-                    device: options.device,
                     configuration: options.configuration.feed,
                     callbackProperties,
                 });

package/dist/factory/mqtt-pull-executable-service-factory.js

@@ -10,12 +10,12 @@ import { noOpExecutableService } from '../service/no-op-executable-service.js';
 export class MqttPullExecutableServiceFactory {
     /**
      * Creates a new MQTT pull executable service factory.
-     * @param devicesProviderRegistry - Registry of device providers for adapter-based sources
-     * @param devicesAdapterRegistry - Registry of device adapters for transforming provider output
+     * @param providerFactoryRegistry - Registry of device providers for adapter-based sources
+     * @param adapterRegistry - Registry of device adapters for transforming provider output
      */
-    constructor(devicesProviderRegistry, devicesAdapterRegistry) {
-        this.devicesProviderRegistry = devicesProviderRegistry;
-        this.devicesAdapterRegistry = devicesAdapterRegistry;
+    constructor(providerFactoryRegistry, adapterRegistry) {
+        this.providerFactoryRegistry = providerFactoryRegistry;
+        this.adapterRegistry = adapterRegistry;
     }
     /**
      * Creates the appropriate provider factory based on the feed configuration type.
@@ -28,16 +28,17 @@ export class MqttPullExecutableServiceFactory {
     createProviderFactory(options) {
         switch (options.configuration.type) {
             case 'adapter': {
-                const provider = this.devicesProviderRegistry.get(options.device);
-                if (!provider) {
-                    throw new Error(`No provider registered for device: ${options.device}`);
+                const device = options.configuration.properties.device;
+                const providerFactory = this.providerFactoryRegistry.get(device);
+                if (!providerFactory) {
+                    throw new Error(`No provider registered for device: ${device}`);
                 }
-                const adapter = this.devicesAdapterRegistry.get(options.device);
+                const adapter = this.adapterRegistry.get(device);
                 if (!adapter) {
-                    throw new Error(`No adapter registered for device: ${options.device}`);
+                    throw new Error(`No adapter registered for device: ${device}`);
                 }
                 return {
-                    providerFactory: new AdapterProviderFactory(provider, adapter),
+                    providerFactory: new AdapterProviderFactory(providerFactory, adapter),
                     interval: options.configuration.properties.interval,
                 };
             }

package/dist/factory/mqtt-push-executable-service-factory.js

@@ -23,9 +23,10 @@ export class MqttPushExecutableServiceFactory {
     create(options) {
         switch (options.configuration.type) {
             case 'bridge': {
-                const adapter = this.devicesAdapter.get(options.device);
+                const device = options.configuration.properties.device;
+                const adapter = this.devicesAdapter.get(device);
                 if (!adapter) {
-                    throw new Error(`No adapter registered for device: ${options.device}`);
+                    throw new Error(`No adapter registered for device: ${device}`);
                 }
                 return new MqttBridgeService(options.configuration.properties, options.callbackProperties, adapter);
             }

package/dist/factory/mqtt-service-factory.js

@@ -36,13 +36,11 @@ export class MqttServiceFactory {
         };
         const gridEnergyPublisher = this.mqttFeedExecutableServiceFactory.create({
             configuration: configuration.properties.meters.grid,
-            device: configuration.properties.device,
             energyType: 'grid',
             callbacks,
         });
         const sunEnergyPublisher = this.mqttFeedExecutableServiceFactory.create({
             configuration: configuration.properties.meters.solar,
-            device: configuration.properties.device,
             energyType: 'solar',
             callbacks,
         });

package/dist/factory/rest-service-factory.js

@@ -20,12 +20,10 @@ export class RestServiceFactory {
     create(configuration) {
         const gridEnergyProvider = this.em1StatusProviderFactory.create({
             energyType: 'grid',
-            device: configuration.properties.device,
             configuration: configuration.properties.meters.grid,
         });
         const solarEnergyProvider = this.em1StatusProviderFactory.create({
             energyType: 'solar',
-            device: configuration.properties.device,
             configuration: configuration.properties.meters.solar,
         });
         return new RestService(gridEnergyProvider, solarEnergyProvider, {

package/dist/provider/asymmetric-emea-provider.js

@@ -0,0 +1,104 @@
+import { logger } from '../utils/logger.js';
+import CircuitBreaker from 'opossum';
+/**
+ * Generic Asymmetric EMA Provider using algebraic interpolators.
+ * Implements exponential moving average (EMA) with different smoothing factors
+ * for rising and falling values, allowing asymmetric response to changes.
+ *
+ * @template T - The type of value this provider supplies
+ */
+class InnerAsymmetricEMAProvider {
+    /**
+     * Creates a new InnerAsymmetricEMAProvider.
+     * @param provider - The underlying provider to fetch raw values from
+     * @param interpolator - The interpolator to use for blending values
+     * @param options - Configuration options for the asymmetric EMA calculation
+     * @throws {Error} If alphaRise or alphaFall is not between 0 and 1
+     */
+    constructor(provider, interpolator, options) {
+        this.provider = provider;
+        this.interpolator = interpolator;
+        this.options = options;
+        this.ema = null;
+        if (options.alphaRise < 0 || options.alphaRise > 1) {
+            throw new Error('alphaRise must be between 0 and 1');
+        }
+        if (options.alphaFall < 0 || options.alphaFall > 1) {
+            throw new Error('alphaFall must be between 0 and 1');
+        }
+    }
+    /**
+     * Fetches a value from the wrapped provider and updates the EMA.
+     * On first call, initializes the EMA with the fetched value.
+     * On subsequent calls, interpolates between the new value and current EMA,
+     * using alphaRise if the value is increasing or alphaFall if decreasing.
+     * @returns A promise that resolves to the updated EMA value
+     */
+    async get() {
+        const newValue = await this.provider.get();
+        if (this.ema === null) {
+            this.ema = newValue;
+        }
+        else {
+            // Determine if value is rising or falling
+            const comparison = this.options.comparator(newValue, this.ema);
+            const alpha = comparison >= 0 ? this.options.alphaRise : this.options.alphaFall;
+            this.ema = this.interpolator.interpolate(newValue, this.ema, alpha);
+        }
+        return this.ema;
+    }
+    /**
+     * Gets the current EMA value without fetching a new value.
+     * @returns The current EMA value, or null if not yet initialized
+     */
+    getCurrentEMA() {
+        return this.ema;
+    }
+    /**
+     * Resets the EMA to its initial state.
+     * The next call to get() will reinitialize the EMA.
+     */
+    reset() {
+        this.ema = null;
+    }
+}
+/**
+ * Resilient Asymmetric EMA Provider with circuit breaker pattern.
+ * Wraps an InnerAsymmetricEMAProvider with resilience features, providing
+ * fallback to the last known EMA value when the underlying provider fails.
+ *
+ * @template T - The type of value this provider supplies
+ */
+export class AsymmetricEMAProvider {
+    /**
+     * Creates a new AsymmetricEMAProvider with circuit breaker protection.
+     * @param provider - The underlying provider to fetch raw values from
+     * @param interpolator - The interpolator to use for blending values
+     * @param asymmetricEmaOptions - Configuration options for the asymmetric EMA calculation
+     */
+    constructor(provider, interpolator, asymmetricEmaOptions) {
+        this.provider = new InnerAsymmetricEMAProvider(provider, interpolator, asymmetricEmaOptions);
+        this.circuitBreaker = new CircuitBreaker(this.provider.get.bind(this.provider), {
+            timeout: 5000, // 5 seconds
+        }).fallback(() => {
+            const fallbackValue = this.provider.getCurrentEMA();
+            if (fallbackValue) {
+                logger.warn('Using Asymmetric EMA value as fallback for ResilientProvider');
+                return fallbackValue;
+            }
+            else {
+                logger.error('No Asymmetric EMA value available for fallback in ResilientProvider');
+                throw new Error('No Asymmetric EMA value available for fallback');
+            }
+        });
+    }
+    /**
+     * Fetches the value from the wrapped provider with resilience features.
+     * If the underlying provider fails or times out, falls back to the last known EMA value.
+     * @returns A promise that resolves to the EMA value
+     * @throws {Error} If no EMA value is available for fallback when the provider fails
+     */
+    get() {
+        return this.circuitBreaker.fire();
+    }
+}

package/dist/provider/interpolator.js

@@ -0,0 +1,54 @@
+/**
+ * Collection of built-in interpolators for common data types.
+ * Provides factory methods for creating interpolators for numbers, objects, arrays,
+ * and identity transformations.
+ */
+export const Interpolators = {
+    /**
+     * Creates a linear interpolator for numbers.
+     * Uses the formula: alpha * newValue + (1 - alpha) * previousValue
+     * @returns An interpolator for numeric values
+     */
+    number: () => ({
+        interpolate: (newVal, prevVal, alpha) => alpha * newVal + (1 - alpha) * prevVal,
+    }),
+    /**
+     * Creates a composite interpolator for objects.
+     * Applies property-specific interpolators to each field of the object.
+     * @template T - The object type with string keys
+     * @param interpolators - A record mapping property names to their interpolators
+     * @returns An interpolator that applies the appropriate interpolator to each property
+     */
+    object: (interpolators) => ({
+        interpolate: (newVal, prevVal, alpha) => {
+            const result = { ...newVal };
+            for (const key in interpolators) {
+                if (Object.prototype.hasOwnProperty.call(interpolators, key)) {
+                    const interpolator = interpolators[key];
+                    result[key] = interpolator.interpolate(newVal[key], prevVal[key], alpha);
+                }
+            }
+            return result;
+        },
+    }),
+    /**
+     * Creates an interpolator for arrays.
+     * Applies element-wise interpolation using the provided element interpolator.
+     * Assumes arrays have matching lengths.
+     * @template T - The type of array elements
+     * @param elementInterpolator - The interpolator to apply to each array element
+     * @returns An interpolator that processes arrays element by element
+     */
+    array: (elementInterpolator) => ({
+        interpolate: (newVal, prevVal, alpha) => newVal.map((val, i) => elementInterpolator.interpolate(val, prevVal[i], alpha)),
+    }),
+    /**
+     * Creates an identity interpolator that always returns the new value.
+     * Useful when no interpolation is desired.
+     * @template T - The type of values
+     * @returns An interpolator that ignores the previous value and alpha
+     */
+    identity: () => ({
+        interpolate: (newVal) => newVal,
+    }),
+};

package/dist/provider/retryable-provider.js

@@ -0,0 +1,37 @@
+import pRetry from 'p-retry';
+import { logger } from '../utils/logger.js';
+/**
+ * Provider that wraps another provider with automatic retry logic.
+ * Uses exponential backoff strategy to retry failed operations,
+ * making the provider more resilient to transient failures.
+ *
+ * @template T - The type of value this provider supplies
+ */
+export class RetryableProvider {
+    /**
+     * Creates a new RetryableProvider.
+     * @param provider - The underlying provider to wrap with retry logic
+     * @param options - Configuration options for retry behavior
+     */
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+    }
+    /**
+     * Fetches a value from the wrapped provider with automatic retry on failure.
+     * Retries are performed according to the configured retry options with exponential backoff.
+     * @returns A promise that resolves to the provided value
+     * @throws {Error} If all retry attempts are exhausted
+     */
+    get() {
+        const run = async () => {
+            return this.provider.get();
+        };
+        return pRetry(run, {
+            ...this.options,
+            onFailedAttempt: (error) => {
+                logger.warn(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
+            },
+        });
+    }
+}

package/dist/schema/mqtt-configuration.js

@@ -5,6 +5,7 @@ export const energyInformationSchema = z.object({
 export const mqttPushBridgeFeedSchema = z
     .object({
     url: z.string(),
+    device: z.string(),
     topic: z.string(),
 })
     .loose();
@@ -24,6 +25,7 @@ export const mqttPullMockFeedSchema = z
 export const mqttPullAdapterFeedSchema = z
     .object({
     interval: z.number().int().nonnegative(),
+    device: z.string(),
     ip: z.string(),
 })
     .loose();
@@ -56,7 +58,6 @@ export const mqttProviderSchema = z.object({
     provider: z.literal('mqtt'),
     properties: z.object({
         url: z.string(),
-        device: z.string(),
         meters: mqttMetersSchema,
     }),
 });

package/dist/schema/rest-configuration.js

@@ -42,7 +42,12 @@ export const em1StatusSchema = z.object({
      */
     flags: z.array(z.string()).optional(),
 });
-export const restAdapterFeedSchema = z.object({ ip: z.string() }).loose();
+export const restAdapterFeedSchema = z
+    .object({
+    ip: z.string(),
+    device: z.string(),
+})
+    .loose();
 export const restMockFeedSchema = z
     .object({ value: em1StatusSchema.optional() })
     .loose();
@@ -67,7 +72,6 @@ export const restProviderSchema = z.object({
     provider: z.literal('rest'),
     properties: z.object({
         port: z.number().int().positive(),
-        device: z.string(),
         meters: restMetersSchema,
     }),
 });

package/dist/service/rest-service.js

@@ -91,8 +91,6 @@ export class RestService extends AbstractExecutableService {
                 return reply.send({ code: -1, message: err.message });
             }
         });
-        // Alias for JSON-RPC style (POST)
-        //app.post('/rpc/EM1.GetStatus', async () => app.inject({ method: 'GET', url: '/rpc/EM1.GetStatus' }).then(r => r.json()));
         await app.listen({ port: this.properties.port, host: '0.0.0.0' });
         logger.info({ port: this.properties.port }, 'Listening');
         logger.info('REST service started');

package/dist/utils/interpolator.js

@@ -0,0 +1,13 @@
+import { Interpolators } from '../provider/interpolator.js';
+export const em1StatusInterpolator = Interpolators.object({
+    id: Interpolators.identity(),
+    calibration: Interpolators.identity(),
+    current: Interpolators.number(),
+    voltage: Interpolators.number(),
+    act_power: Interpolators.number(),
+    aprt_power: Interpolators.number(),
+    pf: Interpolators.number(),
+    freq: Interpolators.number(),
+    errors: Interpolators.identity(),
+    flags: Interpolators.identity(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v2c-any",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "type": "module",
   "description": "Turn any device into V2C Dynamic Power Control",
   "main": "dist/index.js",
@@ -50,6 +50,8 @@
     "fastify": "^5.0.0",
     "glob": "^13.0.0",
     "mqtt": "^5.10.3",
+    "opossum": "^9.0.0",
+    "p-retry": "^7.1.1",
     "pino-pretty": "^13.1.3",
     "undici": "^7.1.0",
     "zod": "^4.2.1"
@@ -57,6 +59,7 @@
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.1",
+    "@types/opossum": "^8.1.9",
     "eslint": "^9.17.0",
     "eslint-config-prettier": "^9.1.0",
     "prettier": "^3.4.2",