Schedules¶

3.9.9

Proto docs: normalgw.hpl.v1

NF provides a centralized schedule service that manages time-based automation across all connected protocols. Schedules evaluate a current value based on weekly timetables, special events, and effective periods, and can automatically write that value to one or more target points.

Architecture¶

The schedule service sits above the protocol layer and works with any point source -- BACnet, Modbus, Fox, or virtual points.

flowchart LR
    subgraph Sources
        B[BACnet Devices]
        L[Local / Manual]
    end
    subgraph NF
        S[Schedule Service]
        E[Evaluator]
        C[Command Service]
    end
    subgraph Targets
        T1[Point A]
        T2[Point B]
    end
    B -- sync --> S
    L -- create --> S
    S --> E
    E -- value change --> C
    C --> T1
    C --> T2

Schedules can originate from two places:

Local schedules are created directly in the management console or via the API. They live entirely within NF.
Device-sourced schedules are discovered on BACnet devices during scanning and imported automatically. They can be synchronized in either direction.

Schedule Data Model¶

A schedule consists of:

Field	Description
Weekly schedule	Seven daily timetables (Monday--Sunday), each a list of time-value transitions
Special events	Date or date-range overrides that take priority over the weekly schedule
Default value	Fallback when no timetable entry matches the current time
Effective period	Optional start/end date range; the schedule is inactive outside this window
Out of service	Disables evaluation when set
Targets	Points to write to when the effective value changes
Priority for writing	BACnet write priority (1--16) used for target writes

Value Types¶

Schedule values can be real numbers, integers, booleans, enumerated values, or null. Null values are not written to targets.

Evaluation¶

The evaluator runs every 5 seconds and computes the current effective value for each schedule using the following priority order:

Out of service -- return the default value immediately.
Effective period -- if the current time is outside the effective period, return null.
Special events -- check each special event for a date match. If multiple events match, the one with the lowest priority number wins. Within the matching event, find the last time entry at or before the current time.
Weekly schedule -- find the entry for today's day of week, then the last time entry at or before the current time.
Default value -- if nothing else matched.

Targets are only written when the effective value changes, not on every evaluation tick.

Creating Schedules¶

Create schedules from the Schedules page in the management console. Specify a name, default value, and optionally an effective period. After creation, edit the schedule to configure the weekly timetable, special events, and write targets.

Local schedules can optionally be exposed as BACnet objects so that external BACnet clients can read their present value and schedule data. Enable this with the "Expose as BACnet" toggle in the schedule editor.

Write Targets¶

Schedules can automatically write their current effective value to one or more NF points. Configure targets in the Targets tab of the schedule editor by adding point UUIDs.

Writes are dispatched through the command service, which provides:

Automatic priority arbitration when multiple writers target the same point
Lifetime management -- schedule commands are auto-extended every evaluation cycle and auto-released if the schedule is deleted or its targets are cleared
Automatic revert on expiration

Write Status¶

Monitor target write status in the Targets tab or via the GetScheduleTargetStatus / GetAllScheduleTargetStatus API calls. Each target reports one of:

OK -- last write succeeded
RETRYING -- write failed, retrying
FAILED -- all retries exhausted

Special Events¶

Special events override the weekly schedule on specific dates or date ranges. Each event has:

Name -- descriptive label (e.g., "Holiday shutdown")
Priority -- lower numbers take precedence when multiple events overlap
Date or date range -- single date or start/end range
Time-value list -- transitions for the matching day(s), identical in format to a daily schedule

BACnet Integration¶

See BACnet Schedules for details on:

Automatic discovery and import of BACnet schedule objects
Bidirectional synchronization modes
Writing schedule changes back to devices
Exposing local schedules as BACnet objects

API¶

The schedule service is available through the ScheduleManager gRPC service in normalgw.hpl.v1:

CRUD

CreateSchedule -- create a new local schedule
GetSchedules -- list schedules with optional source filters
GetScheduleById -- fetch a single schedule
UpdateSchedule -- modify schedule rules, targets, or settings
DeleteSchedule -- remove a schedule and cancel its active commands

Sync

SyncSchedule -- re-read a device-sourced schedule from its device
WriteScheduleToSource -- write local changes back to the source device (bidirectional sync only)
GetScheduleSyncLog -- paginated audit trail of sync operations

Targets

GetScheduleTargetStatus -- per-schedule target write status
GetAllScheduleTargetStatus -- all schedules with targets

Observation

ObserveScheduleValues -- server-streaming feed of effective value changes, with optional UUID filter