Just Add Power Advanced Image Pull

Version 1.0

Driver Overview

The Just Add Power Advanced Image Pull driver starts, stops, configures, monitors, refreshes, and displays ImagePull snapshots from compatible Just Add Power encoders and decoders. It communicates directly from the RTI XP processor to each manually addressed endpoint through the local justAPI HTTP interface. This is a free driver and does not require a license key.

One driver instance supports up to 32 combined encoders and decoders and five reusable ImagePull Profiles. Commands can target one configured endpoint or All Enabled Endpoints. The driver exposes one RTI Preview Image variable for each configured endpoint, together with useful running-state, saved startup-setting, preview, and communication feedback.

The driver is intended for source previews, room-video previews, troubleshooting, signal-path comparison, service pages, and commissioning interfaces. It supports manual preview publication, per-endpoint recurring preview control, one-command capture workflows, and explicit RTI preview clearing. It complements the Just Add Power switching driver; it does not perform matrix routing, CEC control, OSD, video-wall control, or general endpoint administration.

Supported Products and Firmware

Version 1.0 supports Omega and Ultra Series devices running justOS B1.1.0 or later and MaxColor devices running MAX v3.5.2 or later. ImagePull is available on both encoders and decoders.

Native 2G Series systems and Omega or Ultra devices operating in 2G Mode are not supported by this driver. justAPI is not available in 2G Mode, and Just Add Power specifies that temporary ImagePull on native 2G must be started through a persistent Telnet session. Supporting that safely requires a separate Telnet transport and is outside the scope of this justAPI driver.

Version 1.0 provides the 160, 320, and 640 pixel widths supported by justAPI 1.1.2 across the supported product families. MaxColor can provide larger snapshots through CLI configuration, but those series-specific sizes are intentionally excluded from the initial common justAPI implementation. The MaxColor MJPEG stream is also not exposed as an RTI image variable.

How ImagePull and the RTI Preview Work

ImagePull runs on the selected Just Add Power endpoint and captures the HDMI video being processed by that endpoint. The driver does not transport or store the snapshot on the XP processor. It publishes the endpoint-hosted image address to an RTI image-type system variable using RTI's IMGURL mechanism. Every RTI interface that displays the image must have the network path required by the project architecture to retrieve that address.

Omega and Ultra endpoints continually generate pull.bmp while ImagePull is running. RTI interfaces use the converted pull.png preview. MaxColor endpoints provide a native pull.jpg snapshot and do not require conversion.

BMP to PNG Conversion

For Omega and Ultra, Refresh Preview sends the documented conversion command to the endpoint through justAPI. The endpoint writes the new conversion to tmp.png and then atomically replaces pull.png. This avoids publishing a partially written PNG. The driver then republishes the stable pull.png address with ForcePropagate so subscribed RTI interfaces request the refreshed image.

The PNG does not update merely because pull.bmp changes. Refresh Preview, Automatic Preview Refresh, or another Refresh Preview operation must run to create a new PNG. ImagePull capture frequency and RTI preview refresh frequency are separate settings.

MaxColor Refresh Preview first verifies that the ImagePull status endpoint is reachable and then republishes pull.jpg. No BMP conversion command is sent to MaxColor.

Configure Endpoints

1. Add one Just Add Power Advanced Image Pull driver to the RTI project.

2. Set Endpoint Count from 0 through 32. Only the selected endpoint sections and command choices appear.

3. Enter a friendly Endpoint Name. Use a clear source or room name such as Apple TV 1, Blu-ray, Office TV, or Family Room TV.

4. Leave Enabled checked for endpoints that may receive ImagePull operations. Disabled endpoints are excluded from individual and All Enabled Endpoints operations.

5. Select Encoder or Decoder. This selection is dealer-facing identification; both device types use the same ImagePull API.

6. Select Omega or Ultra, or select MaxColor. The selection determines whether Refresh Preview generates pull.png or uses pull.jpg. Selecting the wrong series produces an incorrect Preview URL.

7. Enter the endpoint IP Address or local hostname without http:// and without an API path.

8. Leave HTTP Port at 80 unless the endpoint is intentionally accessed through another port. The same configured authority is used for justAPI and the published snapshot address.

9. Confirm that the XP processor can reach each endpoint's justAPI port. Also confirm that the RTI interfaces displaying Preview Image can retrieve the resulting endpoint URL through the installed network design.

Addresses are entered manually so the driver can support manually configured, JADConfig, AMP/VLAN, and AMP Alternate systems without depending on another driver's internal device list.

Configure ImagePull Profiles

Set ImagePull Profile Count from 1 through 5. Each profile stores a friendly name, snapshot width, processing priority, and capture frequency. The profile name appears in Start ImagePull, Capture Preview, and Configure Startup ImagePull command selectors.

Image Width supports 160, 320, and 640 pixels. A 320-pixel image is the recommended general-purpose starting point. Use 160 for small thumbnails or large preview grids. Use 640 when additional detail is genuinely useful. Larger snapshots require more endpoint processing, network transfer, and RTI interface work.

Processing Priority defaults to Low and should normally remain Low. Low gives video processing priority over snapshot generation. High is provided only for installations that have deliberately tested and accepted the effect on the endpoint.

Capture Frequency is the number of seconds between device captures. A value of 3 is a practical starting point. A value of 0 requests the device's high-rate mode and can substantially increase processing and network activity. Do not select 0 merely to make an RTI still-image object appear like video.

Profile capture frequency controls how often the endpoint updates its source snapshot. Preview Refresh Interval separately controls how often this driver converts or republishes the image for RTI. A one-second device capture does not require a one-second PNG conversion.

Assign Commands

Every command contains an Endpoint selector. All Enabled Endpoints applies the operation sequentially to every enabled endpoint with a configured address. Individual choices display the friendly Endpoint Names from Driver Properties.

Start ImagePull accepts Endpoint and ImagePull Profile. It posts the selected width, priority, and frequency to the documented runtime ImagePull command endpoint. The change takes effect immediately and does not alter the saved startup setting. After acceptance, the driver reads the live running state.

Stop ImagePull accepts Endpoint. It sends the documented stop_image_pull runtime command through the justAPI CLI endpoint. The change does not alter the saved startup setting. Some endpoints briefly continue reporting a true running state after accepting Stop, so the driver suppresses automatic preview work immediately and performs up to eight serialized verification reads. When the live state becomes false, the driver clears the RTI Preview Image variable, removes any queued automatic preview refresh for that endpoint, and excludes the confirmed-stopped endpoint from later automatic preview cycles. No reboot is required for runtime Start ImagePull or Stop ImagePull.

Refresh Preview accepts Endpoint. For Omega and Ultra it converts the current pull.bmp to pull.png and republishes the PNG image variable. For MaxColor it verifies ImagePull communication and republishes the native pull.jpg image variable. Refresh Preview does not start ImagePull; start it first if no usable snapshot exists.

Capture Preview accepts Endpoint, ImagePull Profile, and Completion Behavior. It starts runtime ImagePull using the selected profile, verifies the running state, waits for the profile's Capture Frequency plus the Capture Readiness Margin, converts or verifies and publishes the first preview, and then completes according to the selected behavior. Automatic preview work for that endpoint is suppressed during the workflow. Leave Running keeps ImagePull active. Stop After Capture stops ImagePull, verifies the stopped state, and preserves the newly captured RTI Preview Image. Capture Preview does not modify saved startup settings. Only one Capture Preview workflow can be active per endpoint.

Clear Preview accepts Endpoint. It clears the RTI Preview Image variable without stopping ImagePull, deleting files from the endpoint, or changing recurring preview configuration. If Preview Refresh Active remains true, the preview can reappear during the next recurring cycle. Disable preview refresh first when the image should remain clear while ImagePull continues running.

Set Preview Refresh accepts Endpoint and Refresh Mode. Enable starts recurring driver-managed preview conversion or publication for the selected endpoint. Disable stops future recurring refresh for that endpoint and removes its queued automatic preview requests. It does not start or stop ImagePull. A confirmed-stopped endpoint remains excluded until ImagePull is started, even if Preview Refresh Active is enabled. The selected state lasts until changed again or until the driver restarts.

Configure Startup ImagePull accepts Endpoint, Startup Mode, and ImagePull Profile. Enable stores the selected profile as the endpoint's saved ImagePull-on-boot configuration. Disable stores ImagePull as disabled on future boots. The driver posts the setting, issues the documented device save command, and reads the setting back for verification. The driver does not reboot the endpoint. Runtime ImagePull remains controlled separately by Start ImagePull and Stop ImagePull.

Refresh ImagePull State accepts Endpoint. It reads both the live running state and the saved startup setting. Use this after external webUI, Telnet, or API changes, or when state polling is disabled.

Request and Refresh Handling

Startup Delay postpones queued HTTP activity while the processor and network settle after programming or restart. Commands issued during this period remain queued and begin when Driver Ready becomes true.

Refresh State at Startup is disabled by default to prevent a large initial queue. When enabled, the driver reads two ImagePull resources for every enabled endpoint after the Startup Delay. A 32-endpoint system can therefore queue 64 startup reads.

State Poll Interval reads the live running state for all enabled endpoints. Enter 0 to disable recurring polling. When enabled, use 30 to 120 seconds for most installations rather than aggressively polling a state that rarely changes. Saved startup settings are not polled continuously; use Refresh ImagePull State when those settings may have changed externally.

Automatic Preview Refresh defines the initial Preview Refresh Active state applied to every enabled endpoint whenever the driver starts. It is disabled by default. Set Preview Refresh can then enable or disable individual endpoints at runtime. Preview Refresh Interval remains visible in Driver Properties because it controls both property-enabled and command-enabled recurring refresh. Confirmed-stopped endpoints are skipped until a successful Start ImagePull verification reports that they are running again. For Omega and Ultra this means one justAPI PNG conversion request per eligible endpoint per cycle. Use on-demand Refresh Preview whenever continuous preview updates are unnecessary.

Capture Readiness Margin adds 0 through 10 seconds to Capture Preview's initial wait beyond the selected profile's Capture Frequency. The default one-second margin accommodates file-generation timing without requiring a dealer-authored delay. Increase it only if the first captured image is consistently stale on a tested endpoint.

Requests are serialized through one HTTP queue. Request Spacing prevents a burst of back-to-back connections. Maximum Request Queue protects processor memory from repeated macros or refresh cycles. Duplicate automatic state and preview requests for the same endpoint are suppressed while an equivalent request is pending, and a new complete automatic preview cycle is not queued while the preceding cycle remains active. Manual commands are not silently discarded.

For large systems, separate driver instances divided into logical groups such as Encoders, Decoders, Residence, Public Displays, or Building Floors can make All Enabled Endpoints operations faster and safer.

Recommended Initial Settings

Startup Delay: 3 seconds.

Refresh State at Startup: Disabled.

State Poll Interval: 0 for manual state refresh, or 60 seconds when live state tracking is required.

Automatic Preview Refresh: Disabled.

Preview Refresh Interval: 10 seconds when automatic preview updates are required.

Capture Readiness Margin: 1 second.

Request Timeout: 8 seconds.

Request Spacing: 250 milliseconds.

Maximum Request Queue: 200.

Communication Failure Threshold: 3.

Standard Profile: 320 pixels, Low priority, 3 seconds.

GUI Feedback

Each endpoint provides Preview Image for placement on an RTI interface. Preview URL shows the exact address published to that image variable. Last Preview Refresh reports when the driver most recently converted or republished the preview; it does not prove that every RTI panel successfully downloaded and rendered the image.

ImagePull Running comes from the live details endpoint. Running State Known distinguishes a confirmed false value from the initial unqueried state. Preview Refresh Active reports whether this driver is currently scheduled to publish recurring previews for the endpoint; it does not indicate that ImagePull itself is running. Startup ImagePull Enabled and the saved width, priority, and frequency come from the startup settings endpoint. Startup Settings Known distinguishes a confirmed disabled setting from the initial unqueried state.

Communication Available becomes true after a valid justAPI exchange. It becomes false after the configured number of consecutive request failures. This describes API communication with the endpoint, not HDMI signal presence and not successful image rendering on every RTI interface.

Driver Ready indicates that Startup Delay has completed. Operation In Progress and Queued HTTP Requests show serialized driver workload. Last Operation, Last Operation Target, Last Operation Result, Last HTTP Status, and Last Driver Error are global diagnostic values for the most recently processed operation.

Events

ImagePull Start Accepted and ImagePull Stop Accepted mean that justAPI accepted the immediate command. They do not guarantee that an image has already been downloaded by an RTI panel.

Preview Refreshed fires after a successful Omega or Ultra conversion or successful MaxColor status check and IMGURL publication.

Preview Captured fires after the complete Capture Preview workflow succeeds, including verified stopping when Stop After Capture is selected. Preview Cleared fires after Clear Preview clears the selected endpoint's RTI image variable. Preview Refresh Enabled and Preview Refresh Disabled fire when Set Preview Refresh changes the selected runtime recurring-refresh state. Last Operation Target identifies the associated endpoint.

Startup Settings Saved fires after the setting is posted, saved, and read back successfully. ImagePull State Refreshed fires after a manual running-state and startup-setting refresh completes for an endpoint.

ImagePull Operation Failed, Request Queue Full, and Request Timed Out support failure macros and diagnostics. Endpoint Communication Available, Lost, and Restored describe endpoint API reachability. Last Operation Target identifies the endpoint associated with a global event. An All Enabled Endpoints command can generate the corresponding event once for each endpoint processed.

Example Use Cases

1. Place encoder Preview Image variables beside source-selection buttons so users can see what is currently playing before routing a source. Run Refresh Preview when the source page opens.

2. Place decoder Preview Image variables on a service page to compare what the decoder is processing with what the display shows.

3. Compare an encoder preview with its decoder preview to determine whether a video problem begins at the source, within the network video path, or after the decoder.

4. Start ImagePull on selected endpoints during commissioning, refresh previews as needed, and stop ImagePull when troubleshooting is complete.

5. Configure low-bandwidth thumbnail profiles for a large source grid and a separate 640-pixel profile for a detailed service preview.

6. Enable saved startup ImagePull only on endpoints whose previews are used routinely; leave it disabled elsewhere to avoid unnecessary endpoint and network load.

7. Use Capture Preview with Stop After Capture for an on-demand source thumbnail that remains visible without leaving endpoint capture running.

8. Enable Preview Refresh when opening a live source-preview page and disable it when leaving the page so only visible previews consume conversion and HTTP resources.

9. Disable Preview Refresh and then run Clear Preview when closing a service popup that should not retain its last image.

TraceViewer Logging

Enable Trace logs startup, accepted operations, validation failures, communication failures, and recovery. Verbose HTTP Trace additionally logs the method, API path, endpoint, sanitized request body, response status, response body, and elapsed time.

Leave Verbose HTTP Trace disabled during normal operation. It can generate substantial output during All Enabled Endpoints operations, state polling, or automatic preview refresh. The driver never logs image bytes because it publishes image URLs rather than downloading the image through JavaScript.

Troubleshooting

If Driver Ready remains false, verify Startup Delay and confirm that the driver completed initialization after the latest project transfer.

If an endpoint never becomes Communication Available, verify its configured address and port, confirm the XP processor can reach the endpoint network, and open the endpoint's justAPI details/imagepull resource from a device with equivalent network access.

If ImagePull Running remains unknown, run Refresh ImagePull State and inspect Last HTTP Status, Last Driver Error, and TraceViewer. A valid false value means ImagePull is confirmed stopped; unknown means no valid state has been received.

If Stop ImagePull is accepted but the first state response remains true, allow the driver to complete its bounded verification sequence. This is a normal transitional response on some endpoints. The driver reports a failure only if the endpoint remains in the wrong state after all eight verification attempts.

If an endpoint URL still displays the last snapshot after Stop ImagePull, this does not mean capture is still running. The endpoint retains its last pull.bmp, pull.png, or pull.jpg file after stopping. The driver uses the live details/imagepull response as the authoritative state and clears its RTI Preview Image variable after a verified Stop. A manual Refresh Preview can deliberately republish the retained last snapshot even while capture is stopped.

If Preview Image is blank on Omega or Ultra, first run Start ImagePull, allow time for a BMP capture, and then run Refresh Preview. Confirm that pull.bmp exists on the endpoint and that the conversion command creates pull.png.

If Preview Image is blank on MaxColor, run Start ImagePull and Refresh Preview, then confirm that pull.jpg opens from the network used by the RTI interface.

If the API succeeds but an RTI panel remains blank, test the exact Preview URL shown by the driver from the panel's network path. API access by the XP processor does not by itself prove that a controller on another VLAN can retrieve the snapshot.

If a preview appears stale, remember that Omega and Ultra pull.png updates only when Refresh Preview performs another BMP to PNG conversion. Also confirm that the profile Capture Frequency is not slower than the requested preview refresh cycle.

If Capture Preview publishes the preceding frame instead of the new first frame, increase Capture Readiness Margin by one second and retest. The workflow waits for the selected Capture Frequency plus this margin before conversion or publication.

If Clear Preview appears only briefly, check Preview Refresh Active. Clear Preview intentionally does not disable recurring refresh; issue Set Preview Refresh with Disable first when the preview must remain clear.

If Queued HTTP Requests grows continuously, disable automatic preview refresh and state polling, increase their intervals, look for repeatedly triggered macros, and retain the default request spacing. Do not shorten intervals simply to force faster GUI animation.

If Startup Settings Saved does not fire, confirm that the settings post, device save command, and verification read all completed successfully. Configure Startup ImagePull does not reboot the endpoint and does not replace the separate runtime Start or Stop command.