Sandstar Port Manager
Tag Definition for the Sandstar Controls Engine
Define the tags that power Sandstar's hardware-agnostic controls engine.
Port Manager is where you define and manage the tags that drive Project Sandstar -- a hardware-agnostic controls engine that takes hardware-level protocols like I2C, GPIO, and UART and exposes them to Project Haystack. The tags you define in Port Manager are what Sandstar's engine reads and writes.
Browse your device tree, define point tags in bulk, and sync everything in real time. Port Manager gives you one screen to configure thousands of points across dozens of devices, turning hours of manual setup into minutes.
Why It Matters
Sandstar bridges the gap between raw hardware interfaces (I2C, GPIO, UART) and the semantic world of Project Haystack tags. But that abstraction only works when every point is properly tagged -- the engine needs to know what a point is (zone temp, damper command, schedule) to act on it. Port Manager is the tool that defines this mapping, making the controls engine truly hardware-agnostic.
Who It's For
- Controls engineers defining Haystack tag structures for Sandstar projects
- System integrators mapping hardware I/O points to Sandstar's tag model
- Commissioning teams bulk-tagging points across devices
Three-Panel Workspace
Browse your device tree on the left, edit tags in the center, and reference documentation on the right -- all in one view. Designed for commissioning workflows where context switching kills productivity.
The engineering unit for this point's value. Used by SkySpark for conversions and display.
Marker tag indicating a temperature measurement point.
Channel Browser
Navigate every I/O channel on the device in an organized, expandable tree. Channels are grouped by physical input -- universal analog, digital, I2C sensors, PWM outputs, and virtual points. Configured channels are highlighted so you can instantly see what's been set up and what still needs attention.
- ✓ Channels grouped by hardware pin and I/O type
- ✓ Green dots mark configured points at a glance
- ✓ Exclusive groups auto-disable unused siblings
- ✓ pointQuery values shown inline with copy-on-click
Structured Tag Editor
Configure each point with the right tags, units, and metadata. The editor organizes tags into logical sections -- Identity, Haystack markers, signal processing -- with context-sensitive controls. Mandatory tags are marked, dropdowns offer valid choices, and toggle switches make marker tags effortless.
- ✓ Collapsible sections: Identity, Haystack, Signal Processing
- ✓ Smart controls: toggles for markers, dropdowns for enums, unit pickers
- ✓ Conditional fields appear when parent markers are enabled
- ✓ Add custom tags with typed value inputs (Str, Number, Bool, Ref, Dict)
Schema-Driven Tagging with XETO
Port Manager uses XETO -- Project Haystack's extensible type system -- to describe every channel type the Sandstar engine supports. No hardcoded tag lists, no guessing which tags belong together.
When you select a channel, Port Manager fetches the XETO schema from the device, then dynamically builds the right form: mandatory tags are pre-filled, optional tags are grouped by category, and conditional tags only appear when their parent marker is enabled.
hysteresis and its child tags appear. Disable it and they vanish -- no clutter.Instant Search
Find the right Haystack prototype in seconds with built-in FlexSearch. Type a few keywords and matching protos appear instantly, organized by category. Select one and the correct marker tags are applied to your point automatically -- no need to memorize tag combinations.
The All Points table gives you a sortable, filterable overview of every configured point on the device. See channels, names, values, sync status, and protos in one dense, scannable grid.
- ✓ FlexSearch indexes 40+ Haystack prototypes across 10 categories
- ✓ Auto-generates pointQuery from selected markers
- ✓ All Points table with sortable columns and click-to-edit
| Ch | Name | Kind | Unit | Value | Proto |
|---|---|---|---|---|---|
| 1112 | Zone Temp 1 | Number | °F | 72.4 | air temp sensor |
| 501 | BME280 Humidity | Number | %RH | 45.2 | air humidity sensor |
| 2100 | Fan Enable | Bool | -- | true | fan run cmd |
| 3001 | Cooling Setpoint | Number | °F | 74.0 | air temp sp |
| Ch | Name | Value | Status | Sync |
|---|---|---|---|---|
| 1112 | Zone Temp 1 | 72.4 | ok | synced |
| 500 | BME280 Temperature | 71.8 | ok | synced |
| 3001 | Cooling Setpoint | 74.0 | ok | pending |
| 3002 | Heating SP Override | 68.0 | -- | new |
| 2100 | Fan Enable | true | error | synced |
Real-Time Sync
Every change you make is tracked and synced to the device in real time. The sync column shows you exactly which points are up-to-date, which have pending edits, and which are newly created. Hit Save and your changes write directly to the device -- no export/import dance required.
- ✓ Per-point sync status: synced, pending, new
- ✓ Live value and error status from the device
- ✓ Dirty state tracking with Ctrl+S save shortcut
- ✓ Cached data available offline from IndexedDB
Multi-Device Management
Connect to multiple Sandstar controllers and SkySpark servers simultaneously. Switch between devices with a click -- your connection state, cached points, and configuration follow you. Every device type speaks the same language in Port Manager.
Tech Stack
Architecture
Capabilities
- Channel Browser -- tree navigation for device I/O channels and points
- Bulk Tag Editor with validation and auto-complete
- Full-Text Search powered by FlexSearch across all points and tags
- Real-Time SkySpark Sync -- changes write directly to the folio database
- Three-Panel UI -- browse, edit, and reference documentation simultaneously
Build Pipeline
- TypeScript Check:
npx vue-tsc -b - Vite Build:
npx vite buildproduces optimizeddist/ - Pod Sync:
dist/copied into Fantom pod resources - Fantom Build: Pod compiled for SkySpark 3.1.8
Requirements
- SkySpark 3.1.8+
- bassgCommon 3.1+ shared library
- Modern browser (Chrome, Firefox, Safari, Edge)
Interested in this project?
Explore the source code, contribute, or get in touch.