Skip to content
iiot-unified-namespace logo

IIoT Unified Namespace

iiot-unified-namespace

Unified Namespace (UNS) architecture for IIoT. Topic hierarchy, NATS subjects, and data flow patterns.

SKILL.md

Full skill instructions

IIoT Unified Namespace

Overview

The Unified Namespace (UNS) is a centralized, real-time data hub that organizes all IIoT data following the ISA-95 hierarchy. It provides a single source of truth for all operational data.

Core Principles

  1. Single Source of Truth - All data flows through UNS
  2. ISA-95 Aligned - Topic structure mirrors equipment hierarchy
  3. Report-by-Exception - Only publish changes, not constant polling
  4. Decoupled Architecture - Producers and consumers are independent

Topic Hierarchy

NATS Subject Pattern

iiot.{site}.{area}.{line}.{machine}.{sensor}.{metric}

Examples:
iiot.chicago.plant-a.line-001.mch-001.tmp-001.value
iiot.chicago.plant-a.line-001.mch-001.tmp-001.quality
iiot.chicago.plant-a.line-001.mch-001.>.alarms

Hierarchy Levels

LevelNATS TokenExampleDescription
1iiotiiotRoot namespace
2{site}chicagoPhysical location
3{area}plant-aPlant/​Area
4{line}line-001Production line
5{machine}mch-001Equipment
6{sensor}tmp-001Device ID
7{metric}valueData type

Metric Types

MetricDescriptionPayload
valueCurrent reading{ value: number, time: string }
qualityData quality{ quality: number, time: string }
alarmsActive alarms{ id, severity, message, time }
stateEquipment state{ state: string, since: string }
configConfigurationDevice-specific config

Wildcard Subscriptions

NATS supports powerful wildcard patterns:

// All sensors on a specific machine
'iiot.chicago.plant-a.line-001.mch-001.>'

// All temperature sensors across entire site
'iiot.chicago.*.*.*.tmp-*.value'

// All alarms enterprise-wide
'iiot.*.*.*.*.*.alarms'

// All values from a specific line
'iiot.chicago.plant-a.line-001.*.*.value'

// Single-level wildcard (specific position)
'iiot.chicago.plant-a.*.mch-001.*.value'  // Machine across all lines

TMNL + NATS Integration

Subject Builder

// src/​lib/​iiot/​uns/​subject-builder.ts

import { Schema, Effect } from 'effect'
import type { DeviceId, PlantId, LineId, MachineId } from '@/​lib/​iiot/​schemas'

// Metric types
export const UNSMetric = Schema.Literal('value', 'quality', 'alarms', 'state', 'config')
export type UNSMetric = Schema.Schema.Type<typeof UNSMetric>

// Build a UNS subject from components
export const buildSubject = (
  site: string,
  area: string,
  line: string,
  machine: string,
  sensor: string,
  metric: UNSMetric = 'value'
): string => `iiot.${site}.${area}.${line}.${machine}.${sensor}.${metric}`

// Sensor hierarchy type
export interface SensorHierarchy {
  site: string
  area: string
  lineName: string
  machineName: string
  deviceId: string
}

// Build subject from hierarchy object
export const hierarchyToSubject = (
  h: SensorHierarchy,
  metric: UNSMetric = 'value'
): string =>
  `iiot.${h.site}.${h.area}.${h.lineName}.${h.machineName}.${h.deviceId}.${metric}`

// Parse a subject back to components
export const parseSubject = (subject: string): SensorHierarchy | null => {
  const parts = subject.split('.')
  if (parts.length < 7 || parts[0] !== 'iiot') return null

  return {
    site: parts[1],
    area: parts[2],
    lineName: parts[3],
    machineName: parts[4],
    deviceId: parts[5],
  }
}

Publishing Readings via Holonet

// src/​lib/​iiot/​uns/​publisher.ts

import { Effect, Schema, Stream } from 'effect'
import { NatsInnerService } from '@/​lib/​holonet/​nats/​inner'
import { MessageDecoder } from '@/​lib/​holonet/​decoder'
import { buildSubject, hierarchyToSubject, type SensorHierarchy } from './​subject-builder'

// Sensor reading schema
const SensorReading = Schema.Struct({
  deviceId: Schema.String,
  value: Schema.Number,
  quality: Schema.Number.pipe(Schema.int()),
  time: Schema.DateFromString,
})
type SensorReading = Schema.Schema.Type<typeof SensorReading>

// UNS value payload (what gets published)
const UNSValuePayload = Schema.Struct({
  value: Schema.Number,
  quality: Schema.Number,
  time: Schema.String,
})

export class UNSPublisher extends Effect.Service<UNSPublisher>()(
  'iiot/​UNSPublisher',
  {
    effect: Effect.gen(function* () {
      const nats = yield* NatsInnerService
      const decoder = yield* MessageDecoder

      // Publish a single reading
      const publishReading = (
        hierarchy: SensorHierarchy,
        reading: SensorReading
      ) =>
        Effect.gen(function* () {
          const subject = hierarchyToSubject(hierarchy, 'value')

          // Encode using MessageDecoder (no JSON.stringify)
          const payload = yield* decoder.encodeBytes(UNSValuePayload)({
            value: reading.value,
            quality: reading.quality,
            time: reading.time.toISOString(),
          })

          // Publish to JetStream for persistence
          yield* nats.jsPublish(subject, payload)

          yield* Effect.log(`Published to ${subject}: ${reading.value}`)
        })

      // Publish quality update
      const publishQuality = (
        hierarchy: SensorHierarchy,
        quality: number,
        time: Date
      ) =>
        Effect.gen(function* () {
          const subject = hierarchyToSubject(hierarchy, 'quality')

          const QualityPayload = Schema.Struct({
            quality: Schema.Number,
            time: Schema.String,
          })

          const payload = yield* decoder.encodeBytes(QualityPayload)({
            quality,
            time: time.toISOString(),
          })

          yield* nats.jsPublish(subject, payload)
        })

      return {
        publishReading,
        publishQuality,
      } as const
    }),
    dependencies: [NatsInnerService.Default, MessageDecoder.Default],
  }
) {}

Subscribing to UNS Data

// src/​lib/​iiot/​uns/​subscriber.ts

import { Effect, Stream, Schema, Option } from 'effect'
import { NatsInnerService } from '@/​lib/​holonet/​nats/​inner'
import { MessageDecoder } from '@/​lib/​holonet/​decoder'
import { parseSubject } from './​subject-builder'

// Incoming UNS message with parsed metadata
const UNSMessage = Schema.Struct({
  subject: Schema.String,
  hierarchy: Schema.Struct({
    site: Schema.String,
    area: Schema.String,
    lineName: Schema.String,
    machineName: Schema.String,
    deviceId: Schema.String,
  }),
  value: Schema.Number,
  quality: Schema.Number,
  time: Schema.DateFromString,
})
type UNSMessage = Schema.Schema.Type<typeof UNSMessage>

export class UNSSubscriber extends Effect.Service<UNSSubscriber>()(
  'iiot/​UNSSubscriber',
  {
    effect: Effect.gen(function* () {
      const nats = yield* NatsInnerService
      const decoder = yield* MessageDecoder

      // Subscribe to a UNS pattern
      const subscribe = (pattern: string) =>
        Effect.gen(function* () {
          const sub = yield* nats.core.subscribe(pattern)

          const ValuePayload = Schema.Struct({
            value: Schema.Number,
            quality: Schema.Number,
            time: Schema.String,
          })

          return Stream.fromAsyncIterable(
            sub[Symbol.asyncIterator](),
            (e) => e as Error
          ).pipe(
            Stream.mapEffect((msg) =>
              Effect.gen(function* () {
                const hierarchy = parseSubject(msg.subject)
                if (!hierarchy) {
                  yield* Effect.log(`Invalid subject: ${msg.subject}`)
                  return Option.none()
                }

                // Decode payload using MessageDecoder
                const payloadResult = yield* decoder
                  .decodeBytes(ValuePayload)(msg.data)
                  .pipe(Effect.either)

                if (payloadResult._tag === 'Left') {
                  yield* Effect.log(`Decode error: ${payloadResult.left.message}`)
                  return Option.none()
                }

                const payload = payloadResult.right

                return Option.some({
                  subject: msg.subject,
                  hierarchy,
                  value: payload.value,
                  quality: payload.quality,
                  time: new Date(payload.time),
                })
              })
            ),
            Stream.filterMap((opt) => opt)
          )
        })

      // Subscribe to all values from a machine
      const subscribeToMachine = (
        site: string,
        area: string,
        line: string,
        machine: string
      ) => subscribe(`iiot.${site}.${area}.${line}.${machine}.*.value`)

      // Subscribe to all values from a line
      const subscribeToLine = (
        site: string,
        area: string,
        line: string
      ) => subscribe(`iiot.${site}.${area}.${line}.*.*.value`)

      // Subscribe to all alarms
      const subscribeToAlarms = (site?: string) =>
        subscribe(site ? `iiot.${site}.*.*.*.*.alarms` : 'iiot.*.*.*.*.*.alarms')

      return {
        subscribe,
        subscribeToMachine,
        subscribeToLine,
        subscribeToAlarms,
      } as const
    }),
    dependencies: [NatsInnerService.Default, MessageDecoder.Default],
  }
) {}

JetStream Streams for UNS

Stream Configuration

// src/​lib/​iiot/​uns/​streams.ts

import { Effect } from 'effect'
import { NatsInnerService } from '@/​lib/​holonet/​nats/​inner'
import type { StreamConfig } from 'nats'

// UNS stream configuration
export const UNS_STREAM_CONFIG: Partial<StreamConfig> = {
  name: 'UNS_IIOT',
  subjects: ['iiot.>'],  // Capture all UNS traffic
  storage: 'file',
  retention: 'limits',
  max_age: 30 * 24 * 60 * 60 * 1_000_000_000, // 30 days in nanos
  max_bytes: 10 * 1024 * 1024 * 1024, // 10GB
  max_msgs_per_subject: 1_000_000, // 1M messages per device
  discard: 'old',
  num_replicas: 1,  // Increase for production
}

// Alarm stream (longer retention)
export const UNS_ALARMS_STREAM_CONFIG: Partial<StreamConfig> = {
  name: 'UNS_ALARMS',
  subjects: ['iiot.*.*.*.*.*.alarms'],
  storage: 'file',
  retention: 'limits',
  max_age: 365 * 24 * 60 * 60 * 1_000_000_000, // 1 year
  max_bytes: 1 * 1024 * 1024 * 1024, // 1GB
  discard: 'old',
  num_replicas: 1,
}

// Create UNS streams
export const createUNSStreams = Effect.gen(function* () {
  const nats = yield* NatsInnerService
  const js = yield* nats.jetstream()

  // Create main UNS stream
  yield* Effect.tryPromise(() =>
    js.streams.add(UNS_STREAM_CONFIG as StreamConfig)
  ).pipe(
    Effect.catchTag('UnknownException', () =>
      Effect.log('UNS_IIOT stream may already exist')
    )
  )

  // Create alarms stream
  yield* Effect.tryPromise(() =>
    js.streams.add(UNS_ALARMS_STREAM_CONFIG as StreamConfig)
  ).pipe(
    Effect.catchTag('UnknownException', () =>
      Effect.log('UNS_ALARMS stream may already exist')
    )
  )

  yield* Effect.log('UNS streams initialized')
})

KV Store for Asset State

// src/​lib/​iiot/​uns/​state-store.ts

import { Effect, Schema } from 'effect'
import { NatsInnerService } from '@/​lib/​holonet/​nats/​inner'
import { MessageDecoder } from '@/​lib/​holonet/​decoder'

// Asset state schema
const AssetState = Schema.Struct({
  deviceId: Schema.String,
  lastValue: Schema.Number,
  lastQuality: Schema.Number,
  lastUpdated: Schema.String,
  status: Schema.Literal('online', 'offline', 'stale', 'error'),
})
type AssetState = Schema.Schema.Type<typeof AssetState>

export class UNSStateStore extends Effect.Service<UNSStateStore>()(
  'iiot/​UNSStateStore',
  {
    effect: Effect.gen(function* () {
      const nats = yield* NatsInnerService
      const decoder = yield* MessageDecoder

      const BUCKET_NAME = 'uns-assets'

      // Get or create KV bucket
      const getBucket = () =>
        Effect.gen(function* () {
          const js = yield* nats.jetstream()
          return yield* Effect.tryPromise(() =>
            js.views.kv(BUCKET_NAME, { history: 5 })
          )
        })

      // Build KV key from hierarchy
      const buildKey = (
        site: string,
        area: string,
        line: string,
        machine: string,
        sensor: string
      ) => `${site}/​${area}/​${line}/​${machine}/​${sensor}`

      // Update asset state
      const updateState = (
        site: string,
        area: string,
        line: string,
        machine: string,
        sensor: string,
        state: AssetState
      ) =>
        Effect.gen(function* () {
          const bucket = yield* getBucket()
          const key = buildKey(site, area, line, machine, sensor)
          const payload = yield* decoder.encodeJson(AssetState)(state)
          yield* Effect.tryPromise(() => bucket.putString(key, payload))
        })

      // Get asset state
      const getState = (
        site: string,
        area: string,
        line: string,
        machine: string,
        sensor: string
      ) =>
        Effect.gen(function* () {
          const bucket = yield* getBucket()
          const key = buildKey(site, area, line, machine, sensor)
          const entry = yield* Effect.tryPromise(() => bucket.get(key))
          if (!entry?.string()) return null
          return yield* decoder.decodeJson(AssetState)(entry.string())
        })

      return {
        updateState,
        getState,
        buildKey,
      } as const
    }),
    dependencies: [NatsInnerService.Default, MessageDecoder.Default],
  }
) {}

Report-by-Exception Pattern

Only publish when values change significantly:

// src/​lib/​iiot/​uns/​rbe.ts

import { Effect, Stream, Ref, Option } from 'effect'

interface RBEConfig {
  deadband: number  // Absolute change threshold
  percentDeadband?: number  // Percentage change threshold
  maxInterval?: number  // Max ms between updates (heartbeat)
}

// Report-by-Exception filter for a stream
export const withReportByException = <A extends { value: number }>(
  config: RBEConfig
) => {
  return (stream: Stream.Stream<A>) =>
    Effect.gen(function* () {
      const lastValueRef = yield* Ref.make<Option.Option<{ value: number; time: number }>>(
        Option.none()
      )

      return stream.pipe(
        Stream.filterEffect((reading) =>
          Effect.gen(function* () {
            const lastOpt = yield* Ref.get(lastValueRef)
            const now = Date.now()

            if (Option.isNone(lastOpt)) {
              // First reading - always publish
              yield* Ref.set(lastValueRef, Option.some({ value: reading.value, time: now }))
              return true
            }

            const last = lastOpt.value

            // Check deadband
            const absoluteChange = Math.abs(reading.value - last.value)
            const percentChange = last.value !== 0
              ? (absoluteChange / Math.abs(last.value)) * 100
              : absoluteChange > 0 ? 100 : 0

            const exceedsDeadband = absoluteChange >= config.deadband
            const exceedsPercent = config.percentDeadband
              ? percentChange >= config.percentDeadband
              : false

            // Check heartbeat interval
            const timeSinceLast = now - last.time
            const needsHeartbeat = config.maxInterval
              ? timeSinceLast >= config.maxInterval
              : false

            if (exceedsDeadband || exceedsPercent || needsHeartbeat) {
              yield* Ref.set(lastValueRef, Option.some({ value: reading.value, time: now }))
              return true
            }

            return false
          })
        )
      )
    })
}

// Example usage:
// const rbeStream = yield* withReportByException({ deadband: 0.1, maxInterval: 60000 })(rawStream)

Sparkplug B Compatibility

For Sparkplug B compliance, use this topic structure:

spBv1.0/​{namespace}/​{group_id}/​{message_type}/​{edge_node_id}/​{device_id}

Message types:
- NBIRTH: Node birth certificate
- NDEATH: Node death certificate
- DBIRTH: Device birth certificate
- DDEATH: Device death certificate
- NDATA: Node data
- DDATA: Device data
- NCMD: Node command
- DCMD: Device command

Sparkplug Topic Builder

// src/​lib/​iiot/​uns/​sparkplug.ts

export type SparkplugMessageType =
  | 'NBIRTH' | 'NDEATH'
  | 'DBIRTH' | 'DDEATH'
  | 'NDATA' | 'DDATA'
  | 'NCMD' | 'DCMD'

export const buildSparkplugTopic = (
  namespace: string,
  groupId: string,
  messageType: SparkplugMessageType,
  edgeNodeId: string,
  deviceId?: string
): string => {
  const base = `spBv1.0/​${namespace}/​${groupId}/​${messageType}/​${edgeNodeId}`
  return deviceId ? `${base}/​${deviceId}` : base
}

// Example:
// buildSparkplugTopic('Factory', 'Chicago', 'DDATA', 'LINE-001', 'TMP-001')
// => 'spBv1.0/​Factory/​Chicago/​DDATA/​LINE-001/​TMP-001'

Best Practices

Topic Design

  1. Keep it flat - Avoid deep nesting beyond 7 levels
  2. Use lowercase - Consistent casing prevents mismatches
  3. Use hyphens - line-001 not line_001 or line.001
  4. Version namespace - iiot.v1 allows future changes

Performance

  1. Use JetStream - Enables replay, persistence, exactly-once
  2. Partition by device - Avoids hot partitions
  3. Report-by-exception - Reduces message volume 90%+
  4. Compress payloads - Use MessagePack or CBOR for high-frequency data

Security

  1. Per-device credentials - Scoped NATS users per device
  2. Subject-based ACLs - Restrict pub/​sub by hierarchy
  3. TLS everywhere - Encrypt all traffic

Related Skills

  • /​iiot-isa95-hierarchy - Equipment hierarchy modeling
  • /​nex-effect-services - Effect-TS NATS patterns
  • /​effect-stream-patterns - Stream processing patterns

References

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View