User Guide¶

Configuration, feature behavior, and troubleshooting for Nx Powertoys operators. Installation and first connect: install.md. Cron examples: scheduling/examples.md. In-app walkthroughs live on Home (/index.html).

Configuration¶

Config file locations:

Windows: C:\Program Files\NxPT\etc\config.json
Linux: /opt/nxpt/etc/config.json

Default:

{
  "Port": "8080",
  "debug": "false"
}

Persistent settings also live in the SQLite database. Status → NxPT Advanced edits NxPT Port and Debug Mode (restart may be required for port changes depending on install). First-install may also write Username, Password, and NxPort when credentials are seeded (see install.md).

Status and NX connection¶

Status (/status.html) is the hub for connection, licensing, advanced settings, and database maintenance.

Nx Server Configuration: Nx Server Port (typically 7001), Nx Username, Nx Password → Submit Changes. Administrator user must have Digest Authentication enabled. First-install may already have seeded these (Windows --nx-user / --nx-password / --nx-port; Linux interactive debconf).
Connection badges: Connected / Not Connected, plus licence badges for Rule Groups, Timelapse, and User Roster.
NxPT Web Page: when NX is Connected, NxPT creates or updates the in-client NxPT Web Page (not an install-time REST script; not licence-gated). If ensure fails, Status shows a one-line warning. Host browser at http://127.0.0.1:{port} still works without the page.
Login gate: some Status sections and all feature management require login (/login.html). Credentials are checked against the NX server (not stored as a separate local account).

If the page is missing (skipped install credentials, or ensure failed), add it in the NX Client: name NxPT, URL http://127.0.0.1:{NxPT listen port}, proxy via this local NX server, Proxy all requested contents enabled. Full recipe: install.md.

Licensing¶

Licence Groups gate features (Status → NxPT Licensing):

Group	Unlocks
1 — Rule Groups	Camera Passwords, Server List, Rule Groups, Timers
2 — Timelapse	Timelapse capture and gallery
3 — User Roster	User Roster management and apply

First-time activation (Status Server ID → activation form → paste keys): install.md. Per-group License Key and Activation Key fields are on Status. Soft Trigger migrate on Status is not licence-gated.

Camera Passwords and Servers¶

Licence Group 1.

Camera Passwords (/passwords.html): credentials, vendor, camera names; optional thumbnails (?showThumbnails); Export Camera List (HTML).
Server List (/servers.html): NX servers OS info (name, platform, variant, version, status, Hardware ID / HWID); Export Server List. HWID is the NX licence-bind identifier shown and exported on Server List — not the Status Server ID used for NxPT licensing.

Rule Groups¶

Licence Group 1. UI: /profiles.html (Rules Manager).

Create/edit named groups of NX event rules; filter the NX rules list; include/exclude rules; enable/disable, edit, delete groups.
Create Soft Trigger: generates the soft-trigger rule in NX for that group.
Apply: enables the group’s rules on NX.
Soft Trigger migrate (Status): recommended when soft-trigger metadata needs rewriting after upgrades; available when Connected and logged in. Licence re-activation remains a separate Status action.

Timers¶

Licence Group 1. UI: /timers.html, status /timer-status.html.

Timers run once and stop unless retriggered:

One-time: Executes at zero, then removed from active list
Retrigger: Resets full duration; manual retrigger available after completion when Allow Retriggers is set
States: Running (counting down), Stopped (completed), Retriggerable (reset before completion)

Per timer: name, duration (h/m/s), optional Allow Retriggers, one or more Rule Groups as targets. List actions: Create Soft Trigger, Start, Retrigger (when allowed). Running timers show status; completed timers offer trigger/start actions.

Schedules¶

Always in nav. UI: /schedule.html, status /schedule-status.html.

Fields: Schedule Name, Cron String, Skip Count, Next Run / Scheduled Time.
Targets (optional): Rule Group, Timer, Timelapse, User Roster. Event-only schedules (no targets) still fire an NX Generic Event — see scheduling/examples.md.
Apply Now runs the schedule immediately (useful for testing).

Cron cookbook and patterns: scheduling/examples.md.

Timelapse¶

Licence Group 2. UI: /timelapse.html, gallery /timelapse-gallery.html?name=….

Define storage + cameras on the Timelapse page; capture only runs when the timelapse is a schedule target.
Snapshot path pattern: {storage}/timelapse/{timelapseId}/{camera}/hi|low/{timestamp}.jpg
Gallery tabs: Snapshots, Archives, Exports
Browse year → month → day → camera; select; delete
Archive: zip (resolution, flatten, optional remove sources, target duration for encode kit)
Export video: requires ffmpeg on the NxPT host PATH; otherwise use Snapshot archive (includes an Archive encode kit for offline MP4)

User Roster¶

Licence Group 3. UI: /user-roster.html.

Named collections of NX Users. Apply pushes each member’s stored desired login enable/disable state (mixed states in one apply). Distinct from NX Witness User Groups (permissions).

Create/edit: name (no spaces), members with Desired Enabled. On New (and for non-members in the Edit picker), Desired Enabled starts from each User’s live NX login state — same idea as Rule Group New; saved members keep their stored Desired on Edit.
Apply on the list page, or attach as a schedule target for recurring apply
Protected Users: owners, administrators (best-effort), and the NxPT service user are never disabled by apply (excluded from the member picker)

Recent Actions Log¶

Unified in-memory log for timers, schedules, rule group changes, user roster applies, and related actions.

Storage: In-memory only; cleared on restart
Configure: Status → NxPT Advanced → Configure Recent Actions Logging, or /logging-config.html
Limit: Default 20 entries (range 1–1000)
View: Timer Status and Schedule Status pages (not embedded on Status)

Database Maintenance¶

Status → Database Maintenance (login required):

Create Backup: Manual backup into the restoreable pool
Restore: Installation backups (Linux DEB upgrades) and Manual backups share one pool
Manual backup purge / Full backup purge: purge Manual only, or all backups in the pool

Windows zip installs do not create Installation backups on upgrade — use Manual backup before replacing binaries. Details: install.md.

Service Management¶

Windows¶

nxpt.exe --install
nxpt.exe --start
nxpt.exe --stop
nxpt.exe --uninstall

Linux¶

sudo systemctl start nxpt
sudo systemctl stop nxpt
sudo systemctl status nxpt
sudo journalctl -u nxpt -f

CLI Options¶

nxpt --help
nxpt --version

Windows-only: --install, --uninstall, --port, --install-directory. First install only: --nx-user, --nx-password, --nx-port (default 7001) — flags skip the TTY prompt; existing config.json is never overwritten. Linux has no nxpt --setup; interactive DEB install uses debconf (skipped when noninteractive, upgrade, or config already exists). Details: install.md.

Troubleshooting¶

Port already in use¶

NxPT checks port availability at startup. Check logs for the bound port. Change via Status → NxPT Port or config.json, then restart the service.

Connection issues¶

Confirm Nx Witness Server is running
Administrator user must have Digest Authentication enabled
Check firewall rules and Nx Server Port on Status
NX versions 5.1.5–6.0.x supported

NxPT Web Page missing in NX Client¶

The page is created when the service is Connected, not at install time. Confirm Status shows Connected. If install skipped credentials, Submit them on Status. If a Status warning says NxPT Web Page ensure failed, use the host browser and the manual NX Client recipe in install.md.

Features not available¶

Check Status licence badges (Groups 1–3) and activation keys
Confirm login for management pages
Timelapse Export needs ffmpeg on PATH; use Archive + encode kit otherwise

Soft Trigger not working¶

Soft Triggers require digest auth enabled for the NxPT user. This is currently a limitation of Nx calling back to itself and directing the call to the NxPT server.

If Status shows a Soft Trigger migrate warning after an upgrade or backup restore, run migrate while Connected and logged in (not licence-gated).

Service won't start¶

Windows: Event Viewer
Linux: sudo journalctl -u nxpt -f

Rule group memberships drop after Nx rule edits¶

Nx APIs represent rule IDs differently across versions ({uuid} legacy vs uuid modern). Nx Powertoys normalizes IDs internally. After upgrading, open and save affected rule groups once to persist normalized mappings.