Use the N.I.N.A. Sync Plugin

The PSF Guard Sync plugin connects a live Target Scheduler catalog to a PSF Guard server. It uploads saved lights and calibration frames, pushes scheduler captures, and exchanges plans and reviewed grades. This removes the need to run manual CLI sync commands between database files.

Install the plugin in N.I.N.A.

PSF Guard hosts a N.I.N.A. plugin repository. After you add this repository as a source, the PSF Guard Sync plugin installs and updates through the N.I.N.A. interface:

1. In N.I.N.A., open Options → Plugins.
2. Add this repository URL:

   https://nina-plugins.psf-guard.com/

3. Turn on “Include beta versions” because PSF Guard Sync releases are currently distributed on the beta channel.
4. Locate PSF Guard Sync in the list of available plugins, install it, and restart N.I.N.A.

Pair N.I.N.A. with a catalog

1. Open Settings → Databases and edit the destination catalog.
2. If you want N.I.N.A. to upload image files, enable Remote image uploads, choose a configured image directory as the receive directory, and save the catalog.
3. Select Generate pairing code next to Pair a client, and copy the code.
4. In the plugin interface, enter the PSF Guard server URL, paste the pairing code, and click connect. The server provides the catalog ID and the credentials for this N.I.N.A. installation.
5. Select Test connection, and then configure your preferred upload and catalog synchronization behavior.

A pairing code is single-use and expires after one hour. Each pairing creates a unique catalog-scoped credential. The PSF Guard server stores only the digest of the credential, and the plugin stores the credential in Windows Credential Manager. Pairing enables scheduler synchronization for the catalog, but does not configure image uploads or the receive directory.

The catalog editor lists all connected installations under Paired clients. You can revoke a single client credential there without affecting other paired clients.

Use a manual API key fallback

A client that does not support pairing can use the following manual setup:

1. Enable Remote scheduler sync on the catalog, and separately enable Remote image uploads if you want to upload files.
2. Select Generate next to Remote API key, copy the key, and save the catalog.
3. Copy the catalog ID from the database list or from its ?db= URL, then enter the server URL, database ID, and API key into the N.I.N.A. plugin.

Generating a new manual key invalidates the previous manual key. It does not affect paired clients. Similarly, revoking a paired client does not invalidate the manual key or other paired clients.

Understand how the plugin works

The plugin listens for image-saved events in N.I.N.A. and supports two capture paths. Direct image mode places the saved FITS or XISF file into an upload queue. Target Scheduler mode waits for the corresponding acquiredimage row, and then queues a bundle that includes the capture metadata, project, target, and planning fields. All uploads run in the background. If the server is offline, the plugin retains the queued items and retries later.

• Direct image uploads are supported: you can upload FITS or XISF light frames, bias frames, darks, dark-flats, and flats without installing Target Scheduler. Calibration frames are added to the PSF Guard calibration library and do not generate image rows in Target Scheduler.
• The plugin performs automatic catalog pushes: each light frame is queued after Target Scheduler records it, which includes the scheduler metadata required by PSF Guard to reconstruct the plan.
• The queue is durable and persistent: queued bundles are stored under the %LOCALAPPDATA%\NINA\PsfGuardSync directory and persist across application restarts. Retrying an upload with an identical filename and hash does not duplicate the catalog entry.
• Previews are generated in the background: large catalog operations create their preview on the server as a background job. The plugin checks progress using a job-specific token, which prevents HTTP timeouts at reverse proxies.
• Data transfer is bi-directional and on-demand: you can perform manual merges, planning pushes, and grade pushes, as well as pull plans and grades back into Target Scheduler.
• Images are identified by stable GUIDs: PSF Guard matches images by GUID and updates parent IDs for projects, targets, templates, and plans while preserving capture counts on the telescope. Pulling grades only modifies the gradingStatus and rejectreason fields.
• The plugin can transfer thumbnails: you can choose to send Target Scheduler thumbnail images alongside the captured data.
• The plugin verifies data integrity during pulls: PSF Guard sends a SHA-256 hash of the response body in the X-Content-SHA256 header. The plugin validates this hash before applying changes to Target Scheduler. This avoids encoding discrepancies that can occur with JSON parsers.

Review staged catalog changes

Each catalog push generates a preview on the server before modifying the destination database. You can view these under Settings → Sync → Staged previews. This list displays previews created in the current browser and previews uploaded by remote N.I.N.A. installations.

Each row shows the destination catalog, operation type, data source, change counts, and expiration time. You can expand the What would change section to inspect individual field changes, grade transitions, rejection reasons, and any database items scheduled for updates, up to a limit of 400 lines.

• Apply writes the staged changes to the destination database.
• Refresh recalculates the comparison between the source bundle and the destination database. Use this if the destination has been modified since the preview was generated.
• Discard deletes the staged preview without modifying the database.

Configure synchronization and upload settings

Once you have paired the client, navigate to Plugins → Installed → PSF Guard Sync in N.I.N.A. and configure the following options:

1. Specify the Target Scheduler database file path (the default path is %LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite).
2. Select whether the plugin should upload each saved light frame directly.
3. Select whether to also upload calibration frames, including bias, dark, dark-flat, and flat frames.
4. Select whether the plugin should push the Target Scheduler database row for each saved light.
5. Choose whether catalog previews should apply automatically or remain staged in the UI for manual review.

Click Test connection before enabling automated features. This tool verifies the server URL, client credentials, catalog selection, protocol version, and server permissions.

Use advanced sequencer instructions

The plugin adds several instructions under the PSF Guard Sync category in N.I.N.A.'s advanced sequencer:

• Check PSF Guard connection: this instruction verifies the server URL, credentials, and selected catalog. You should place this instruction near the start of a sequence. If the server is offline, the sequencer executes the configured error handling behavior.
• Pull PSF Guard planning: this instruction pulls remote projects, targets, templates, and exposure plans and applies them to the local Target Scheduler. You should run this instruction before a Target Scheduler container starts, because a running container might not reload plan data from disk.
• Pull PSF Guard grades: this instruction retrieves reviewed grades and rejection reasons, and applies them to Target Scheduler using the image GUIDs.
• Reconcile PSF Guard catalog: this instruction uploads a complete Target Scheduler snapshot, waits for the server to generate a preview, and optionally applies the changes. This is useful to run at the end of an imaging session.
• Reconcile current target with PSF Guard: this instruction reconciles data only for the current target. You should place this instruction near the end of the target's container. This avoids naming ambiguities, as the server refuses to match targets with duplicate names.
• PSF Guard image upload: this instruction waits for the current image write to complete and then uploads the selected light or calibration frames. This operates independently of Target Scheduler and can be used to override profile-wide upload settings for a single sequence.

Reconciliation instructions wait for Target Scheduler to complete its current database transaction and for the server to generate the preview. The sequence pauses until both actions are complete. Automatic per-capture uploads continue in the background and will retry if they encounter errors.

Resolve common issues