@bradtech/sensor-lorawan 1.1.0

package/src/LoRaWanPipeline.ts

@@ -0,0 +1,443 @@
+import { defaultSensorAdapters } from './defaultAdapters'
+import { BradOSCodec } from './BradOSCodec'
+import type { ConversionOutput } from '@bradtech/sensor'
+import type {
+   CompanyUri,
+   DeviceUri,
+   OkfMetricUri,
+   PlotUri,
+} from '@bradtech/types'
+
+/**
+ * Pure LoRaWAN Uplink message contract from ChirpStack or external Network Server.
+ * Contains purely radio, frame counter, port, and raw binary payload data.
+ * Note: Hardware probe payloads NEVER contain agronomic or soil calibration parameters.
+ */
+export interface PipelineUplinkInput {
+   /** Device metadata from Network Server */
+   deviceInfo?: {
+      /** 64-bit IEEE Extended Unique Identifier in hex (e.g. "0018b20000001234") */
+      devEui?: string
+      /** Human device name (e.g. "b25s004" or "b26w001") */
+      deviceName?: string
+      /** ChirpStack Application UUID */
+      applicationId?: string
+      /** ChirpStack Application Name */
+      applicationName?: string
+      /** Optional generic Network Server metadata tags */
+      tags?: Record<string, string>
+   }
+   /** Alternative flat devEUI property */
+   devEUI?: string
+   /** LoRaWAN Application Port (FPort) indicating the physical channel */
+   fPort?: number
+   /** Frame uplink counter */
+   fCnt?: number
+   /** Base64-encoded binary payload string */
+   data?: string
+   /** Array of receiving gateway metadata records (RSSI, SNR, GPS) */
+   rxInfo?: Array<{
+      gatewayId?: string
+      rssi?: number
+      snr?: number
+      location?: { latitude?: number; longitude?: number; altitude?: number }
+   }>
+   /** Transmission RF metadata (frequency in Hz, DataRate) */
+   txInfo?: {
+      frequency?: number
+      dataRate?: number
+   }
+   /** ISO 8601 message publication timestamp */
+   publishedAt?: string
+   /** Alternative ISO 8601 message timestamp */
+   time?: string
+}
+
+/**
+ * Agronomic & Plot context resolved from the Backoffice / Master Data Management database.
+ * The Backoffice links a physical probe (devEUI) to an agricultural parcel (Plot),
+ * with its specific soil profile, texture classification, and optional lab calibration model.
+ */
+export interface AgronomicPlotContext {
+   /** Canonical Plot identifier or URI (e.g. "plots/parcelle-nord-01" or "parcelle-nord-01") */
+   plot?: PlotUri | (string & {})
+   /** Canonical Company / Tenant identifier or URI (e.g. "companies/domaine-alpha" or "domaine-alpha") */
+   company?: CompanyUri | (string & {})
+   /** Soil texture classification assigned to the plot in Backoffice (e.g. "clay", "sand", "loam", "silt", "peat") */
+   soilTexture?: 'sand' | 'loam' | 'clay' | 'silt' | 'peat' | 'default' | (string & {})
+   /** Custom plot-specific laboratory calibration model (linear regression: y = slope * raw + intercept) */
+   soilLinearRegression?: {
+      slope: number
+      intercept: number
+      modelLabel?: string
+   }
+   /** Optional hardware vendor tag */
+   vendor?: string
+   /** Optional hardware model tag */
+   vendorModel?: string
+}
+
+/**
+ * Normalized output contract representing an immutable DataPoint ready for PostgreSQL storage.
+ */
+export interface PipelineDataPointOutput {
+   /** Canonical device URI (e.g. 'probes/b25s004' or 'weather-stations/b26w001') */
+   device: DeviceUri | (string & {})
+   /** Canonical plot URI (e.g. 'plots/e5eadee3-...') */
+   plot?: PlotUri | (string & {})
+   /** Canonical company/tenant URI (e.g. 'companies/32c18f05-...') */
+   company?: CompanyUri | (string & {})
+   /** Canonical OKF metric identifier */
+   metric: OkfMetricUri | (string & {})
+   /** Calibrated numerical value */
+   value: number
+   /** Human-readable physical unit symbol */
+   unit: string
+
+   /** Kind indicator: 'measured' for direct sensor readings, 'computed' for agronomic algorithms */
+   kind: 'measured' | 'computed'
+   /** Quality and confidence score between 0.0 and 1.0 */
+   confidence: number
+   /** Observation timestamp */
+   timestamp: string
+   /** Comprehensive metadata contract */
+   metadata: Record<string, any>
+}
+
+/**
+ * End-to-End LoRaWAN Telemetry Ingestion & Transformation Pipeline.
+ *
+ * Coordinates:
+ * - IEEE 754 Float32 binary decoding via `BradOSCodec`.
+ * - Automatic hardware sensor attribution (SHT40, Brad soil sensor, Davis, SI1145, BMP280, MP34DT01).
+ * - Routing to decoupled domain converter packages (`@bradtech/sensor-*`).
+ * - Agronomic context enrichment from Backoffice (Plot association, Soil profile, Custom calibration curves).
+ */
+export class LoRaWanPipeline {
+   private static _airConverter = defaultSensorAdapters.canopyAir
+   private static _soilMoistureConverter = defaultSensorAdapters.soilMoisture
+   private static _soilWpConverter = defaultSensorAdapters.soilWaterPotential
+   private static _soilTempConverter = defaultSensorAdapters.soilTemperature
+   private static _soilEcConverter = defaultSensorAdapters.soilEc
+   private static _solarConverter = defaultSensorAdapters.solarRadiation
+   private static _rainConverter = defaultSensorAdapters.rainGauge
+   private static _windConverter = defaultSensorAdapters.wind
+   private static _baroConverter = defaultSensorAdapters.barometricPressure
+   private static _batteryConverter = defaultSensorAdapters.battery
+   private static _acousticSplConverter = defaultSensorAdapters.acousticSpl
+   private static _acousticWeatherConverter = defaultSensorAdapters.acousticWeather
+
+   /**
+    * Ingests a raw LoRaWAN uplink message, decodes binary payload, evaluates domain converters
+    * with optional agronomic plot context provided by the Backoffice, and returns validated DataPoints.
+    *
+    * @param uplink - Incoming ChirpStack LoRaWAN message object (pure radio frame).
+    * @param agronomicContext - Optional agronomic context resolved from Backoffice (Plot ID, Soil Texture, Calibration).
+    * @returns Array of transformed DataPoints.
+    */
+   static process(
+      uplink: PipelineUplinkInput,
+      agronomicContext?: AgronomicPlotContext,
+   ): PipelineDataPointOutput[] {
+      const dataPoints: PipelineDataPointOutput[] = []
+
+      // 1. Resolve Canonical Device & Tenancy Identifiers
+      const rawDeviceName = uplink.deviceInfo?.deviceName || uplink.deviceInfo?.devEui || uplink.devEUI || 'unknown'
+      const deviceUri = this._buildDeviceUri(rawDeviceName)
+      
+      // Plot & Company resolved from Backoffice agronomic context (with fallback to metadata tags)
+      const rawPlot = agronomicContext?.plot || uplink.deviceInfo?.tags?.plot
+      const plotUri = rawPlot ? (rawPlot.startsWith('plots/') ? rawPlot : `plots/${rawPlot}`) : undefined
+
+      const rawCompany = agronomicContext?.company || uplink.deviceInfo?.tags?.company
+      const companyUri = rawCompany ? (rawCompany.startsWith('companies/') ? rawCompany : `companies/${rawCompany}`) : undefined
+
+      const timestamp = uplink.publishedAt || uplink.time || new Date().toISOString()
+      
+      // Soil texture and calibration model come from the Backoffice plot definition
+      const soilTexture = agronomicContext?.soilTexture || (uplink.deviceInfo?.tags?.soilTexture as any) || 'default'
+      const soilLinearRegression = agronomicContext?.soilLinearRegression || this._extractLinearRegression(uplink.deviceInfo?.tags)
+
+      // 2. Build LoRaWAN Radio Metadata Contract
+      const bestGateway = uplink.rxInfo?.[0]
+      const vendor = agronomicContext?.vendor || (uplink.deviceInfo?.tags?.vendor as any) || 'brad'
+      const radioMetadata = {
+         interface: '@bradtech/types:LoRaWanMetadataInterface',
+         vendor,
+         vendorModel: agronomicContext?.vendorModel || uplink.deviceInfo?.tags?.vendorModel || (rawDeviceName.startsWith('b26w') ? 'Brad Weather Station v1' : 'Brad Soil Probe v2.5'),
+         vendorDeviceId: rawDeviceName,
+         integrationType: 'lorawan' as const,
+         devEui: uplink.deviceInfo?.devEui || uplink.devEUI,
+         fPort: uplink.fPort,
+         fCnt: uplink.fCnt,
+         frequency: uplink.txInfo?.frequency,
+         dataRate: uplink.txInfo?.dataRate,
+         rssi: bestGateway?.rssi,
+         snr: bestGateway?.snr,
+         gatewayId: bestGateway?.gatewayId,
+         gatewayCount: uplink.rxInfo?.length || 0,
+      }
+
+      // 3. Emit Network Quality DataPoints
+      if (bestGateway?.rssi !== undefined) {
+         dataPoints.push({
+            device: deviceUri,
+            plot: plotUri,
+            company: companyUri,
+            metric: 'okf:radio/lorawan/rssi',
+            value: bestGateway.rssi,
+            unit: 'dBm',
+            kind: 'measured',
+            confidence: 1.0,
+            timestamp,
+            metadata: radioMetadata,
+         })
+      }
+
+      if (bestGateway?.snr !== undefined) {
+         dataPoints.push({
+            device: deviceUri,
+            plot: plotUri,
+            company: companyUri,
+            metric: 'okf:radio/lorawan/snr',
+            value: Number(bestGateway.snr.toFixed(1)),
+            unit: 'dB',
+            kind: 'measured',
+            confidence: 1.0,
+            timestamp,
+            metadata: radioMetadata,
+         })
+      }
+
+      // 4. Decode Payload via BradOSCodec
+      if (!uplink.fPort || !uplink.data) {
+         return dataPoints
+      }
+
+      // Special Case: FPort 1 (Boot Frame)
+      if (uplink.fPort === 1) {
+         const boot = BradOSCodec.decodeBootPayload(uplink.data)
+         if (boot) {
+            const battOutputs = LoRaWanPipeline._batteryConverter.convert({ voltageMv: boot.batteryMv })
+            for (const b of battOutputs) {
+               dataPoints.push({
+                  device: deviceUri,
+                  plot: plotUri,
+                  company: companyUri,
+                  metric: b.metric,
+                  value: b.value,
+                  unit: b.unit,
+                  kind: 'measured',
+                  confidence: b.confidence,
+                  timestamp,
+                  metadata: {
+                     ...radioMetadata,
+                     bootVersion: boot.version,
+                     buildDoy: boot.buildDoy,
+                     resetReason: boot.resetReason,
+                     ...b.metadata,
+                  },
+               })
+            }
+         }
+         return dataPoints
+      }
+
+      // Standard Telemetry: FPort 2 to 52
+      const channel = BradOSCodec.decodeFPortChannel(uplink.fPort, uplink.data)
+      if (!channel) {
+         return dataPoints
+      }
+
+      const conversionOutputs: ConversionOutput[] = []
+
+      switch (channel.channelType) {
+         case 'canopy_temp': {
+            const outputs = LoRaWanPipeline._runConverter(LoRaWanPipeline._airConverter, {
+               temperature: channel.rawValue,
+               humidity: 60.0,
+            })
+            const tempOut = outputs.find((o) => o.metric.includes('temperature'))
+            if (tempOut) conversionOutputs.push(tempOut)
+            break
+         }
+
+         case 'canopy_hum': {
+            const outputs = LoRaWanPipeline._runConverter(LoRaWanPipeline._airConverter, {
+               temperature: 20.0,
+               humidity: channel.rawValue,
+            })
+            const humOut = outputs.find((o) => o.metric.includes('humidity'))
+            if (humOut) conversionOutputs.push(humOut)
+            break
+         }
+
+         case 'soil_moisture': {
+            // Apply plot-specific soil texture & calibration model from agronomic context
+            const vwcOut = LoRaWanPipeline._runConverter(
+               LoRaWanPipeline._soilMoistureConverter,
+               { depthCm: channel.depthCm || 10, rawValue: channel.rawValue },
+               { soilTexture, soilLinearRegression },
+            )
+
+            conversionOutputs.push(...vwcOut)
+
+            // Automatically compute derived pF matric potential based on plot soil texture
+            if (vwcOut.length > 0) {
+               const wpOut = LoRaWanPipeline._runConverter(
+                  LoRaWanPipeline._soilWpConverter,
+                  { depthCm: channel.depthCm || 10, vwcPercent: vwcOut[0].value },
+                  { soilTexture },
+               )
+               conversionOutputs.push(...wpOut)
+            }
+            break
+         }
+
+         case 'soil_temp': {
+            const tempOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._soilTempConverter, {
+               depthCm: channel.depthCm || 10,
+               temperature: channel.rawValue,
+            })
+            conversionOutputs.push(...tempOut)
+            break
+         }
+
+         case 'soil_ec': {
+            const ecOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._soilEcConverter, {
+               depthCm: channel.depthCm || 10,
+               bulkEcMsCm: channel.rawValue,
+            })
+            conversionOutputs.push(...ecOut)
+            break
+         }
+
+         case 'solar': {
+            const solarOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._solarConverter, { irradianceWm2: channel.rawValue })
+            conversionOutputs.push(...solarOut)
+            break
+         }
+
+         case 'rain': {
+            const rainOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._rainConverter, { tipCount: channel.rawValue })
+            conversionOutputs.push(...rainOut)
+            break
+         }
+
+         case 'wind_speed': {
+            const windOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._windConverter, { speedMs: channel.rawValue })
+            conversionOutputs.push(...windOut)
+            break
+         }
+
+         case 'wind_dir': {
+            const windDirOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._windConverter, { speedMs: 0, directionDegrees: channel.rawValue })
+            conversionOutputs.push(...windDirOut)
+            break
+         }
+
+         case 'pressure': {
+            const baroOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._baroConverter, { pressureHpa: channel.rawValue })
+            conversionOutputs.push(...baroOut)
+            break
+         }
+
+         case 'battery': {
+            const battOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._batteryConverter, { voltageV: channel.rawValue })
+            conversionOutputs.push(...battOut)
+            break
+         }
+
+         case 'acoustic_spl': {
+            const splOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._acousticSplConverter, { rmsDbfs: channel.rawValue })
+            conversionOutputs.push(...splOut)
+            break
+         }
+
+         case 'acoustic_rain':
+         case 'acoustic_wind': {
+            const acWeatherOut = LoRaWanPipeline._runConverter(LoRaWanPipeline._acousticWeatherConverter, {
+               highFrequencyEnergyRms: channel.channelType === 'acoustic_rain' ? channel.rawValue : -80,
+               lowFrequencyEnergyRms: channel.channelType === 'acoustic_wind' ? channel.rawValue : -80,
+            })
+            conversionOutputs.push(...acWeatherOut)
+            break
+         }
+      }
+
+      // Map conversion outputs to final DataPoints
+      for (const out of conversionOutputs) {
+         const isDerived = out.metric.includes('potential') || out.metric.includes('par_ppfd') || out.metric.includes('percentage')
+
+         dataPoints.push({
+            device: deviceUri,
+            plot: plotUri,
+            company: companyUri,
+            metric: out.metric,
+            value: out.value,
+            unit: out.unit,
+            kind: isDerived ? 'computed' : 'measured',
+            confidence: out.confidence,
+            timestamp,
+            metadata: {
+               ...radioMetadata,
+               sensorSource: channel.sensorSource,
+               sensorModel: channel.sensorModel,
+               ...out.metadata,
+               interface: isDerived ? '@bradtech/types:ComputedMetadataInterface' : '@bradtech/types:LoRaWanMetadataInterface',
+            },
+         })
+      }
+
+      return dataPoints
+   }
+
+   /**
+    * Executes a converter instance and injects class name, model code, and semver version into metadata.
+    */
+   private static _runConverter(
+      converter: any,
+      raw: any,
+      context?: any,
+   ): ConversionOutput[] {
+      const outputs: ConversionOutput[] = converter.convert(raw, context)
+      return outputs.map((out) => ({
+         ...out,
+         metadata: {
+            converterClass: converter.constructor.name,
+            modelCode: converter.modelCode,
+            modelVersion: converter.modelVersion,
+            ...out.metadata,
+         },
+      }))
+   }
+
+   /**
+    * Normalizes raw hardware device names into canonical OKF device URIs.
+    */
+   private static _buildDeviceUri(deviceName: string): string {
+      const clean = deviceName.trim().toLowerCase()
+      if (clean.startsWith('probes/') || clean.startsWith('weather-stations/')) {
+         return clean
+      }
+      if (clean.startsWith('b26w') || clean.startsWith('station')) {
+         return `weather-stations/${clean}`
+      }
+      return `probes/${clean}`
+   }
+
+   /**
+    * Helper extracting linear regression calibration parameters if provided in tags.
+    */
+   private static _extractLinearRegression(tags?: Record<string, string>) {
+      if (!tags?.soilSlope || !tags?.soilIntercept) return undefined
+      const slope = parseFloat(tags.soilSlope)
+      const intercept = parseFloat(tags.soilIntercept)
+      if (isNaN(slope) || isNaN(intercept)) return undefined
+      return {
+         slope,
+         intercept,
+         modelLabel: tags.soilModelLabel,
+      }
+   }
+}

package/src/defaultAdapters.ts

@@ -0,0 +1,82 @@
+import { Sensor } from '@bradtech/sensor'
+import {
+   CanopyMicroclimateConverter,
+   EvapotranspirationConverter,
+   GroundFrostRiskConverter,
+} from '@bradtech/sensor-air'
+import {
+   SoilMoistureConverter,
+   SoilWaterPotentialConverter,
+   SoilTemperatureConverter,
+   SoilElectricalConductivityConverter,
+} from '@bradtech/sensor-soil'
+import {
+   SolarRadiationConverter,
+   RainGaugeConverter,
+   WindConverter,
+   BarometricPressureConverter,
+} from '@bradtech/sensor-weather'
+import { BatterySoCConverter, SolarHarvestingConverter } from '@bradtech/sensor-power'
+import { AcousticSplConverter, AcousticWeatherConverter } from '@bradtech/sensor-acoustic'
+
+/**
+ * Pre-instantiated out-of-the-box domain sensor adapters dictionary.
+ * Avoids redundant allocations across high-frequency message processing pipelines.
+ */
+export const defaultSensorAdapters = {
+   /** In-canopy temperature, humidity, dew point and foliar VPD adapter */
+   canopyAir: new CanopyMicroclimateConverter(),
+   /** Hargreaves-Samani FAO-56 daily reference evapotranspiration (ET0) adapter */
+   evapotranspiration: new EvapotranspirationConverter(),
+   /** Roland Stull wet-bulb temperature and ground frost risk evaluator */
+   frostRisk: new GroundFrostRiskConverter(),
+   /** Multi-depth soil volumetric water content (VWC %) calibrated adapter */
+   soilMoisture: new SoilMoistureConverter(),
+   /** Van Genuchten soil matric water potential (kPa) and pF scale adapter */
+   soilWaterPotential: new SoilWaterPotentialConverter(),
+   /** Multi-depth soil profile thermistor adapter */
+   soilTemperature: new SoilTemperatureConverter(),
+   /** 25°C temperature-normalized soil electrical conductivity (mS/cm) adapter */
+   soilEc: new SoilElectricalConductivityConverter(),
+   /** Broadband solar pyranometer (W/m²) and PAR PPFD photon flux adapter */
+   solarRadiation: new SolarRadiationConverter(),
+   /** Tipping bucket rainfall accumulation (mm) and rain rate (mm/h) adapter */
+   rainGauge: new RainGaugeConverter(),
+   /** Anemometer wind speed (km/h) and 16-cardinal vane direction adapter */
+   wind: new WindConverter(),
+   /** Absolute barometric pressure and sea-level QNH reduction adapter */
+   barometricPressure: new BarometricPressureConverter(),
+   /** Chemistry-aware non-linear battery SoC (%) and brownout adapter */
+   battery: new BatterySoCConverter(),
+   /** Solar panel photovoltaic harvesting voltage adapter */
+   solarHarvesting: new SolarHarvestingConverter(),
+   /** MEMS microphone Sound Pressure Level (dBA SPL) adapter */
+   acousticSpl: new AcousticSplConverter(),
+   /** Acoustic rain droplet impact and aerodynamic wind turbulence adapter */
+   acousticWeather: new AcousticWeatherConverter(),
+}
+
+/**
+ * Registers all built-in Brad domain sensor adapters into the global Quatrain Sensor facade.
+ *
+ * @returns The initialized Sensor singleton class for fluent chaining.
+ */
+export function registerDefaultSensorAdapters(): typeof Sensor {
+   Sensor.addAdapter(defaultSensorAdapters.canopyAir, 'canopyAir')
+   Sensor.addAdapter(defaultSensorAdapters.evapotranspiration, 'evapotranspiration')
+   Sensor.addAdapter(defaultSensorAdapters.frostRisk, 'frostRisk')
+   Sensor.addAdapter(defaultSensorAdapters.soilMoisture, 'soilMoisture')
+   Sensor.addAdapter(defaultSensorAdapters.soilWaterPotential, 'soilWaterPotential')
+   Sensor.addAdapter(defaultSensorAdapters.soilTemperature, 'soilTemperature')
+   Sensor.addAdapter(defaultSensorAdapters.soilEc, 'soilEc')
+   Sensor.addAdapter(defaultSensorAdapters.solarRadiation, 'solarRadiation')
+   Sensor.addAdapter(defaultSensorAdapters.rainGauge, 'rainGauge')
+   Sensor.addAdapter(defaultSensorAdapters.wind, 'wind')
+   Sensor.addAdapter(defaultSensorAdapters.barometricPressure, 'barometricPressure')
+   Sensor.addAdapter(defaultSensorAdapters.battery, 'battery')
+   Sensor.addAdapter(defaultSensorAdapters.solarHarvesting, 'solarHarvesting')
+   Sensor.addAdapter(defaultSensorAdapters.acousticSpl, 'acousticSpl')
+   Sensor.addAdapter(defaultSensorAdapters.acousticWeather, 'acousticWeather')
+
+   return Sensor
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './BradOSCodec'
+export * from './LoRaWanPipeline'
+export * from './defaultAdapters'