# Kincony Smart Controller Macro Module

Crestron SIMPL Windows Integration & Signal Specification Reference
Module Version: v1.0.0
Target System: Crestron 3-Series / 4-Series
Protocol: TCP/IP Socket

## 1. Overview & File Package

This macro module provides seamless TCP/IP communication and hardware control between Crestron control processors and Kincony smart relay/controller hardware. The package consists of five core files that must be placed in your active SIMPL Windows project directory:

USH
Kincony_Ctrl.ush
USP
Kincony_Ctrl.usp
UM2
Kincony_Module.um2
UMC
Kincony_Module.umc
CLZ
KinconyHelper.clz

## 2. Integration & Instructions

Quick Setup Guide

1. Copy all five (5) files into your SIMPL Windows project directory.
2. Relaunch or refresh SIMPL Windows.
3. In the Symbol Library window, expand `Project Modules` → `Relay Control`.
4. Drag and drop the "Kincony_Module" macro into your program view.

Signal Direction Concept Notice
• Module Output Pins (To Logic): Report status/feedback FROM the hardware TO Crestron.
• Module Input Pins (From Logic): Send control commands FROM Crestron TO the hardware.

## 3. Network Configuration & System Status

Signal Name | Module Pin Type | Direction (SIMPL) | Description
--- | --- | --- | ---
IP | Parameter | Input (Parameter) | Target IP address of the Kincony controller (e.g., `192.168.1.200`).
Port | Parameter | Input (Parameter) | TCP Port number (Web UI: Protocol → General → TCP Server).
Connected | Digital Output Pin | Output (To Logic) | TCP Socket Connection Status. High (1) = Connected / Socket Active. Low (0) = Disconnected.

## 4. Digital Input (DI Ports) & Digital Output (DO Ports / Relays)

### Digital Inputs (DI Ports)

Signal Name | Module Pin Type | Hardware Interface | Description & Behavior
--- | --- | --- | ---
Di_FB[1] .. [128] | Digital Output Pin | Physical `DI Port [x]` | Real-time status of physical DI Port. High (1): Active. Low (0): Inactive.

### Digital Outputs / Relays (DO Ports)

Signal Name | Module Pin Type | Hardware Interface | Description & Behavior
--- | --- | --- | ---
Do_All_On | Digital Input Pin | All `DO Ports` | Pulse High (1) to close (turn ON) all physical relay ports.
Do_All_Off | Digital Input Pin | All `DO Ports` | Pulse High (1) to open (turn OFF) all physical relay ports.
Do_On[1] .. [128] | Digital Input Pin | Target `DO Port [x]` | Pulse High (1) to energize/close specific relay port.
Do_Off[1] .. [128] | Digital Input Pin | Target `DO Port [x]` | Pulse High (1) to de-energize/open specific relay port.
Do_Toggle[1] .. [128] | Digital Input Pin | Target `DO Port [x]` | Pulse High (1) to toggle state of specific relay port.
Do_FB[1] .. [128] | Digital Output Pin | Target `DO Port [x]` | Real-time feedback. High (1): Closed / ON. Low (0): Open / OFF.

## 5. Analog Inputs (AI Ports) & Analog Outputs (AO Ports)

### Analog Inputs (AI Ports)

Signal Name | Module Pin Type | Hardware Interface | Description & Resolution Range
--- | --- | --- | ---
Ai_FB[1] .. [64] | Analog Output Pin | Physical `AI Port [x]` | Raw sensor value (4–20mA current or 0–5V voltage). • ESP32: `0 – 4095` • ADS1115: `0 – 26489`

### Analog Outputs (AO Ports)

Signal Name | Module Pin Type | Hardware Interface | Description & Range
--- | --- | --- | ---
Ao_Value[1] .. [32] | Analog Input Pin | Physical `AO Port [x]` | Output level control. Range: 0 – 255 (Maps to DC 0 – 10V).
Ao_FB[1] .. [32] | Analog Output Pin | Physical `AO Port [x]` | Feedback of output level. Range: 0 – 255 (Maps to DC 0 – 10V).

## 6. Infrared Control (IR Ports & Commands)

Signal Name | Module Pin Type | Hardware Domain | Description & Operation
--- | --- | --- | ---
IR_ID | Analog Input Pin | Command Index | IR command ID index (1 – 192).
IR_Tube | Analog Input Pin | Physical `IR Port` | Physical IR emitter port index (Port 1 / Port 2).
IR_Learn | Digital Input Pin | Hardware IR Window | Rising edge triggers IR learning for `IR_ID`.
IR_Send | Digital Input Pin | Physical `IR Port` | Rising edge sends stored command at `IR_ID`.
IR_Delete | Digital Input Pin | Memory Store | Rising edge erases command at `IR_ID`.
IR_Learn_FB_ID | Analog Output Pin | System Feedback | Reports `IR_ID` for latest Learn status event.
IR_Learn_OK | Digital Output Pin | Status Pulse | Pulsed High on learn success.
IR_Learn_Timeout | Digital Output Pin | Status Pulse | Pulsed High on learn timeout.
IR_Learn_Error | Digital Output Pin | Status Pulse | Pulsed High on learn error.