Introduction

The KOS Dispense SDK (@kosdev-code/kos-dispense-sdk) provides domain-specific models and React integration patterns for building beverage dispensing applications. Rather than working directly with low-level device APIs, developers use pre-built models that represent dispense hardware components, consumer selection workflows, and dispensing operations.

KOS itself is a generic embedded device OS and framework. The Dispense SDK adds dispense-specific behavior on top of this generic foundation, providing abstractions for both consumer and non-consumer interfaces to dispensing hardware.

What Problems Does the SDK Solve?

Building dispensing applications requires understanding device topology, managing ingredient assignments, handling pour operations, and presenting selection interfaces. The Dispense SDK addresses these challenges by:

1. Dispense-specific domain models: Models like HolderModel, PumpModel, and NozzleModel provide dispense-focused abstractions instead of generic device APIs
2. Organized topology management: The AssemblyModel singleton loads and organizes device structure (boards, holders, pumps, nozzles)
3. Consumer UI foundation: The DeviceAssembly → Nozzle → Availability hierarchy provides selection-focused models for consumer interfaces
4. React integration patterns: Pre-built hooks and contexts (useAssemblyContext, useCuiKit, useNozzlePour) simplify React integration
5. Trouble integration: Built-in trouble tracking and resolution utilities
6. Extension points: Companion models and extension types allow customization without forking

Target Audiences and Use Cases

Consumer UI Applications

Applications where users (self-serve customers, drive-thru operators, kitchen staff) select and dispense beverages:

• Self-serve consumer touch screen UIs
• Crew-server consumer UIs (drive-thru, kitchen staff)
• Mobile ordering apps with dispense integration
• Self-service kiosks

Primary models: DeviceAssemblyModel, NozzleModel, AvailabilityModel
Key patterns: CUI Kit, selection workflows, pour operations

Non-Consumer UI (NCUI) Applications

Dispenser admin applications for device configuration, troubleshooting, and management (used by technicians, managers, and occasionally crew):

• Device configuration and setup
• Ingredient management and assignment
• Pump calibration and diagnostics
• Holder fuel gauge monitoring
• Trouble resolution workflows
• Device dashboards and status monitoring

Primary models: AssemblyModel, HolderModel, PumpModel, BoardModel
Key patterns: Hardware topology access, component operations, trouble handling

Two Model Hierarchies

The SDK provides two complementary hierarchies designed for different application needs:

Hardware Hierarchy (NCUI/Admin Apps)

AssemblyModel (singleton)
├── HolderContainer
│   └── HolderModel[]
│       ├── IngredientModel
│       └── PumpContainer (child pumps)
├── PumpContainer
│   └── PumpModel[]
└── BoardContainer
    └── BoardModel[]

Focus: Direct hardware representation
Use when: Building NCUI/admin apps, maintenance tools, or need direct hardware access
Entry point: AssemblyModel via Assembly.instance(id).build()

Consumer UI Hierarchy

DeviceAssemblyModel (singleton)
└── NozzleModel[]
    └── AvailabilityModel[]
        (brands, beverages, flavors)

Focus: Selection-focused representation for consumer experiences
Use when: Building consumer UIs (self-serve or crew-server), beverage selection interfaces
Entry point: DeviceAssemblyModel via DeviceAssembly.instance(id).build()

Prerequisites

• KOS application environment with @kosdev-code/kos-ui-sdk installed
• Understanding of KOS model lifecycle (init, load, ready)
• Basic React knowledge (for React integration)
• Access to a KOS device or simulator

Installation

The Dispense SDK is typically included in KOS workspace projects. If installing manually:

npm install @kosdev-code/kos-dispense-sdk

Model Registration

Register dispense models using the KosModelRegistry:

import { KosModelRegistry } from '@kosdev-code/kos-dispense-sdk';
// Register all dispense models
KosModelRegistry.dispense.models();

This registers all dispense SDK models including Assembly, Holder, Pump, DeviceAssembly, Nozzle, Availability, and their containers.

Quick Start Examples

Consumer UI Pattern

import {
  KosModelRegistry,
  DeviceAssemblyProvider,
  useDeviceAssemblyContext
} from '@kosdev-code/kos-dispense-sdk';
// Register models during app initialization
KosModelRegistry.dispense.models();
// Use in React components
function BeverageSelection() {
  const { model: deviceAssembly, nozzlePaths } = useDeviceAssemblyContext();
  // Auto-discover nozzles rather than hardcoding paths
  const nozzle = nozzlePaths?.[0] ? deviceAssembly?.getNozzle(nozzlePaths[0]) : undefined;
  const brands = nozzle?.visibleBrands || [];
  return (
    <div>
      {brands.map(brand => (
        <button key={brand.id} onClick={() => nozzle?.setSelectedBrand(brand)}>
          {brand.data.name}
        </button>
      ))}
    </div>
  );
}
// Wrap your app with the provider
function App() {
  return (
    <DeviceAssemblyProvider>
      <BeverageSelection />
    </DeviceAssemblyProvider>
  );
}

Hardware/NCUI Pattern

import {
  KosModelRegistry,
  AssemblyProvider,
  useAssemblyContext
} from '@kosdev-code/kos-dispense-sdk';
// Register models during app initialization
KosModelRegistry.dispense.models();
// Use in React components
function IngredientManagement() {
  const { model: assembly } = useAssemblyContext();
  const holders = assembly?.holderContainer.holders || [];
  return (
    <div>
      {holders.map(holder => (
        <div key={holder.path}>
          <h3>{holder.name}</h3>
          <p>Ingredient: {holder.ingredientName || 'Unassigned'}</p>
          <p>Fill: {holder.fillPercent}%</p>
        </div>
      ))}
    </div>
  );
}
// Wrap your app with the provider
function App() {
  return (
    <AssemblyProvider>
      <IngredientManagement />
    </AssemblyProvider>
  );
}

When to Use Which Hierarchy

Next Steps

• For Consumer UIs: Read Consumer UI Foundation and CUI Kit
• For NCUI/Admin Apps: Read Assembly Model & Hardware Topology and Hardware Component Models
• For React Integration: See React Integration Patterns
• For Pour Operations: See Pouring Operations

Additional Resources

• KOS UI SDK Documentation – General KOS model patterns
• Model Lifecycle Guide – Understanding init/load/ready
• Event System Documentation – KOS EventBus and topics