@parallaxcontrol/node-red-control/tools/usage-guide.md

A comprehensive package of Node-RED nodes designed to seamlessly integrate with the Parallax Control Engine, offering enhanced control capabilities for AV Automation.

Parallax Node-RED Tools Usage Guide
Overview
The Parallax Control system extends Node-RED with specialized nodes for audiovisual (AV) 
systems and hardware integration. 
NOTE: The MCP Server contains further details in regards to each nodes functionality, 
these instructions are just a summary with basic examples to get you familiar with the 
context. Each nodes manifest should be reference prior to building out any Node-RED 
flows with that node. 
All Parallax nodes communicate using a standardized JSON protocol where msg.payload 
contains specific properties that control system state and behavior.
Key Principle: Always use Parallax nodes first, then standard Node-RED nodes, and only create 
custom function nodes as a last resort.
Rule: Prior to using a Parallax node you must call its tool to learn how it should be wired. Never guess or assume the wiring or node configuration.
Core JSON Schema
Parallax nodes expect structured messages with these common properties:
*	msg.payload.Input - Specifies which input to use (1-based indexing)
*	msg.payload.Value - The data value (boolean, number, or string)
*	msg.payload.JoinId - Unique identifier for feedback/state management
Example: {"Input": 1, "Value": true} or {"JoinId": "lights_main", "Value": 
false}
Important Considerations for Parallax Nodes:
The parallax nodes may contain virtual inputs when there is more than 1 input available from an upstream node. If for example the user wants to compare two logic states with an AND-GATE, you would wire both outputs of the upstream node to the same AND-GATE input, and in the AND-GATE specify how many inputs to check for. If a node has multiple input selectons, such as the relay node, use the input-select-node to determine which virtual input to select.
Node Categories
Logic Nodes
Process boolean logic and conditional operations:
*	and-gate: Outputs true only when ALL inputs are true
*	or-gate: Outputs true when ANY input is true
*	inverter-gate: Flips boolean values (true ? false)
*	set-reset-latch: Simulates relay behavior with Set/Reset/Toggle operations
*	bool-toggle: Three-input toggle with Set(1)/Reset(2)/Toggle(3) controls
Usage: Connect input-select node to choose which operation to perform.
Helper Nodes
Simplify common automation patterns:
*	input-select: Routes specific input values to downstream nodes (bypasses Node-RED's 
single-input limitation)
*	message-array: Bundles multiple values into array format
*	extract-message-data: Extracts specific fields from payloads
*	save-signal-state/recall-signal-state/clear-signal-state: Manage persistent data across 
system restarts
*	send-single-dictionary/set-feedback: Handle UI feedback and state reporting
Hardware Nodes
Embedded Hardware (CM4-Pro Series)
Physical I/O on Parallax CM4-Pro hardware:
*	cm4-pro-relay: Controls physical relay outputs (use input-select with Input 1=On, 
2=Off)
*	cm4-pro-digital-input: Monitors digital input state changes
Serial Communication Ports
Access via standard node-red-node-serialport:
*	RS485-1: /dev/ttyAMA4
*	RS485-2: /dev/ttyAMA3
*	RS232-1: /dev/ttyAMA5
MQTT Integration
For Unity Software integration, use node-red-contrib-aedes package.
Third-Party AV Hardware
*	biamp-tesira-connect: Establishes connection to Biamp DSP systems
*	biamp-tesira-command: Sends TTP commands to Biamp devices
*	av-pro-ac-cx42/av-pro-ac-cx62: Controls AVPro Edge matrix switchers
Implementation Guidelines
Message Structure
Always structure messages as JSON objects:
{
  "Input": 1,
  "Value": true,
  "JoinId": "device_power"
}
Node Selection Priority
1.	First: Use available Parallax nodes
2.	Second: Use standard Node-RED nodes
3.	Last: Create custom function nodes only when necessary
Hardware Integration Approach
1.	Identify the control protocol (Serial, TCP/IP, Telnet, HTTP/S, SSH, WebSocket, Relay)
2.	Use appropriate Parallax hardware node if available
3.	For custom commands, search online documentation for device-specific syntax
4.	Present commands to user for approval before implementation
5.	Reference manufacturer documentation for exact command formats
Input Selection Pattern
Since Node-RED limits each node to one physical input, use the input-select node to create 
multiple virtual inputs for downstream Parallax nodes.
State Management
*	Use save-signal-state before setting feedback to persist data through reboots
*	Use recall-signal-state to restore previous states on system startup
*	Use clear-signal-state to reset stored values when needed
Advanced Usage
Custom Command Integration
When users request specific device commands (power on/off, input switching, etc.):
1.	Search for manufacturer's latest command documentation
2.	Verify command syntax and parameters
3.	Present commands to user for approval
4.	Implement using appropriate hardware node with proper JSON structure
Troubleshooting
*	Always verify JSON payload structure matches node expectations
*	Check that Input values use 1-based indexing (not 0-based)
*	Ensure JoinId values are unique across the system
System Architecture Notes
*	Parallax nodes handle the complexity of device communication protocols
*	Standard JSON messaging ensures consistent behavior across all nodes
*	Input-select pattern solves Node-RED's single-input architectural limitation
*	State persistence ensures system reliability across power cycles
Final Note: The nodes manifest is the final source of truth for deciding how to wire and configure nodes. 
IF you have questions or need clarification for ambiguous requests you are allowed to ask the user.