Albicchiere

Dispenser Business Logic

Server-side handling of IoT events and communications with ALBI dispensers

Dispenser Communications

This document outlines the server-side handling of IoT events and communications with ALBI dispensers.

Shadow Updates

Bag Shadow Events

Delta Events

  • Topic: $aws/things/+/shadow/name/bag/update/delta
  • Handler: shadowBagDeltaEvent
Implementation

Middleware endpoint: /dispenser/dispensers/bag_shadow_delta

Handles bag shadow delta events by:

  1. Validating admin access
  2. Extracting thingName and bagSerial from event
  3. Processing bag NFC read events through dispenserService.bagNfcReadEvent()
  4. Updating dispenser state with new bag information

  • bagNfcReadEvent(thingName: string, bagSerial: string)

    • Calls updateBagInfoOnDispenser() with "bagNfcRead" action
    • Updates bag ownership if necessary
    • Publishes "bag_inserted" event
    • Sends notification for custom temperature bags

  • updateBagInfoOnDispenser(action, opts)

    • Uses strategy pattern for different update types
    • Creates appropriate payload based on action
    • Updates dispenser shadow via IoT Data Plane

Update Events

  • Topic: $aws/things/+/shadow/name/bag/update/accepted
  • Handler: shadowBagUpdateEvent
Implementation

Middleware endpoint: /dispenser/dispensers/bag_shadow_update

Handles bag shadow updates by:

  1. Extracting thingName and state from event
  2. Processing smart bag removal when no state fields are present
  3. Updating quantityLeft when smart bag is still present
  4. Publishing bag_removed event when applicable

  • updateShadow(thingName: string, shadowName: string, payload: ShadowPayload)

    • Sends shadow update via IoT Data Plane
    • Handles both desired and reported states
    • Supports multiple shadow types (bag, device)

  • getShadowData(dispenser: IDispenser, shadowName: string)

    • Retrieves current shadow state
    • Handles error cases and logging
    • Returns parsed shadow data

Device Shadow Events

  • Topic: $aws/things/+/shadow/name/device/update/accepted
  • Handler: shadowDeviceUpdateEvent
Hard Reset Handling

When ownerId is empty in both desired and reported states, performs a hard reset of the dispenser:

  • Clears ownership data
  • Removes configuration
  • Resets device to factory settings
State Update Handling

When receiving reported state updates, updates the dispenser database with:

  • Basic info (serial, name, WiFi settings)
  • Firmware version
  • Service schedule
  • Wine ready timestamp
  • Operating mode
  • Parental control status
  • Battery status
  • Display settings
  • Active alerts

Lifecycle Events

Connect Event

  • Topic: $aws/events/presence/connected/+
  • Handler: dispenserLifecycleConnectEvent
Implementation
  • Updates dispenser status to "online"
  • Records connection timestamp

Disconnect Event

  • Topic: $aws/events/presence/disconnected/+
  • Handler: dispenserLifecycleDisconnectEvent
Implementation
  • Updates dispenser status to "offline"
  • Records last connection timestamp
  • Ignores "DUPLICATE_CLIENTID" disconnections

Telemetry Events

Metrics

  • Topic: /dispenser/+/metrics
  • Handler: dispenserMetricsEvent
Implementation

Currently logs event data only. [Additional details pending]

Diagnostics

  • Topic: /dispenser/+/diagnostics
  • Handler: dispenserDiagnosticsEvent
Implementation

Currently logs event data only. [Additional details pending]

NFC and Device Info

Bag NFC Read

  • Topic: /dispenser/+/nfcread
  • Handler: bagNfcReadEvent
Implementation

Updates dispenser service with bag serial number on NFC scan events.

Dispenser Read

  • Topic: /dispenser/+/read
  • Handler: dispenserReadEvent
Implementation

Responds to read requests with:

  • Owner ID
  • Locale settings

Image Processing

  • Topic: /dispenser/+/getimagelabel
  • Handler: getImageLabelEvent
Caching
  • Implements in-memory caching for recently requested images
  • Caches by bag serial number
Image Retrieval
  • Supports both standard vintage and user vintage images
  • Retrieves images from appropriate S3 bucket
  • Handles both AWS path and custom domain URLs
Transfer Protocol
  • Supports chunked image transfer
  • Handles start byte and buffer length parameters
  • Returns base64 encoded image chunks
  • Provides initial image length information

Logging

  • Topic: /dispenser/+/logs
  • Handler: getDispenserLogs
Implementation

Middleware endpoint: /dispenser/dispensers/dispenser_logs

Handles dispenser logs by:

  1. Validating admin access
  2. Extracting event details (thingName, timestamp, result)
  3. Processing different log codes (L01, W05, E01-E07, etc.)
  4. Publishing appropriate events based on log type

Topic Structure

All topics include the thing name as a parameter, which can be accessed using topic(3) or topic(5) depending on the topic structure.

Notes

  • All IoT events use SQL version "beta" where specified
  • The + wildcard in topics allows listening to events from all dispensers
  • Many events include error handling and logging for debugging purposes

Previous

Alexa Skill (Dispenser)

Next

Dispenser Events

On this page