voltage-ems-query

name: voltage-ems-query description: Use this skill when the user asks about VoltageEMS live data: channels, devices, points, real-time values, historical sensor data, alarms, rules, models, instances, routing, Redis RTDB, service health, or system status. Use monarch CLI commands to answer — do NOT inspect source code, local database files, or config YAMLs to answer questions about current platform state.

VoltageEMS Query Skill

Use monarch as the primary interface for all live VoltageEMS platform data.

Core Rules

• Execute monarch commands to answer questions about current platform state.
• Do not read source code files or SQLite database files to answer live data questions.
• Do not read config YAML files to answer questions about running device data.
• Always add --json when you need to parse or chain results.
• When --host is needed, pass it as a global flag (before the subcommand).

Command Discovery

monarch --help
monarch <subcommand> --help        # e.g. monarch alarms --help
monarch channels --help

Global Flags

Authentication

monarch requires no login. All commands talk directly to local services.

Connecting to a Remote Machine

# Option A — SSH (monarch lives on the remote machine)
ssh root@192.168.30.62 'monarch --json alarms list'

# Option B — local monarch binary + --host flag
#   (requires service ports 6001/6002/6004/6006 to be reachable from localhost)
monarch --host 192.168.30.62 --json alarms list

Prefer Option A when monarch is already installed on the target machine and you are not sure which ports are exposed.

Command Map

Channels (comsrv :6001)

monarch channels list
monarch channels list --json
monarch channels status <id>
monarch channels health
monarch channels points list <channel_id>
monarch channels points get <channel_id> <point_type> <point_id>

Models — Products & Instances (modsrv :6002)

monarch models products list
monarch models products get <id>
monarch models instances list
monarch models instances list --product <product_id>
monarch models instances get <id>

Business Rules (modsrv :6002)

monarch rules list
monarch rules get <id>
monarch rules executions <id>           # recent execution results

Alarms (alarmsrv :6007)

monarch alarms list                     # active alerts
monarch alarms list --level 3           # high-severity only
monarch alarms list --channel <id>
monarch alarms list --keyword overvolt
monarch alarms get <id>
monarch alarms rules                    # alarm rule definitions
monarch alarms rules --enabled          # only enabled rules
monarch alarms rules --channel <id>
monarch alarms rule-get <id>
monarch alarms events                   # historical trigger+recovery events
monarch alarms events --level 3
monarch alarms events --event-type trigger
monarch alarms events --rule <rule_id>
monarch alarms stats                    # alert count by level
monarch alarms monitor                  # alarm monitor loop status

Historical Data (hissrv :6004)

monarch history latest <redis_key> <point_id>
# e.g. monarch history latest inst:9:M 101

monarch history query <redis_key> <point_id>
monarch history query inst:9:M 101 --from 2026-05-01T00:00:00Z --to 2026-05-12T00:00:00Z
monarch history query inst:9:M 101 --page 2 --size 50

# Batch: query multiple points in one request (max 20 series)
monarch history batch --series inst:9:M,101 --series inst:9:M,102 --from 2026-05-01T00:00:00Z
monarch history batch --series inst:9:M,101 --series inst:12:M,201 --from 2026-05-01T00:00:00Z --to 2026-05-12T00:00:00Z --limit 500

monarch history channels                # channels with recorded history
monarch history metrics                 # storage backend statistics
monarch history health                  # hissrv health check

Redis RTDB (direct :6379)

monarch rtdb get <key> <field>          # HGET key field
monarch rtdb scan <pattern>             # KEYS pattern
monarch rtdb inspect <key>              # HGETALL
monarch rtdb patterns                   # list known key patterns

Routing

monarch routing list                    # channel→instance routing table
monarch routing get <channel_id>

Service & System Health

monarch doctor                          # full system health check
monarch services status
monarch logs list
monarch logs view <service> -n 100
monarch logs tail <service> --grep ERROR

Intent → Command Mapping

Multi-step Pattern

When a user provides a name but you need an ID:

# Step 1: find ID
monarch channels list --json
# Step 2: use ID in subsequent command
monarch alarms list --channel <id> --json

Output Preference

• Always add --json when chaining commands or parsing results programmatically.
• JSON success envelope: {"success": true, "data": ...}
• JSON error envelope: {"success": false, "error": "..."}
• When presenting results to the user, extract data and format meaningfully.
• For alarm warning levels: 1 = low, 2 = medium, 3 = high.
• redis_key format: inst:<instance_id>:M for measurement points, comsrv:<channel_id>:T for telemetry.

Redis Key Reference

Guardrails

• Read-only: Do not run commands that mutate state (channels control, channels adjust, rules enable/disable, rtdb set, rtdb del) unless the user explicitly asks to make a change.
• No source diving: Never open *.rs, *.yaml, or *.db files to answer live data questions.
• No Redis direct: Prefer monarch history for historical data over raw monarch rtdb inspection.
• If a service is not reachable, report the error message from monarch directly; do not guess at data.

Terminology