Crestron SIMPL Windows Programming

This note covers SIMPL Windows specifically. For SIMPL# Pro C# programming, see control-systems/crestron-simpl-sharp. For the Crestron platform overview, see control-systems/crestron-basics.

SIMPL Windows (Simple Integrated Machine Programming Language) is Crestron's graphical programming environment for building control system logic. A SIMPL program represents the control system's behavior as a signal-flow diagram: hardware devices emit and receive signals, and logic symbols connect them to create automated behavior. SIMPL has been the dominant Crestron programming environment for over two decades and remains the tool of choice for service work on 3-Series installations and straightforward 4-Series projects. Understanding SIMPL is fundamental to Crestron work in the field.

Signal Types

Every connection in SIMPL is one of three signal types. Selecting the wrong signal type is the most common beginner error.

Digital signals — Binary values: 1 (high/true/on) or 0 (low/false/off). Represented as orange lines in SIMPL. Used for button presses, relay states, boolean conditions, power status, any on/off state. Digital signals are the most common signal type. Examples: Display_Power_On, Mic_Mute_FB, Room_Occupied.

Analog signals — 16-bit unsigned integer values from 0 to 65535. Represented as blue lines. Used for volume levels, brightness, position, any variable that takes a range of values. Crestron uses 16-bit scaling: 0% = 0, 100% = 65535. Intermediate values scale linearly. Examples: Volume_Level, Screen_Position, Brightness_Output.

Serial signals — Variable-length ASCII or binary strings. Represented as pink/purple lines. Used for RS-232 commands, IP strings, display names, text to show on panels. Examples: Display_RS232_TX, Source_Name_Text, Calendar_Room_Name.

Signals are named by the programmer. Signal names are global within the SIMPL program — connecting two symbols with the same signal name on both creates a logical connection, even if they are physically far apart on the canvas. This is the primary mechanism for large program organization: a touchpanel button press signal named Source_HDMI_Select is consumed by the display symbol's input switching logic anywhere in the program.

The SIMPL Program Canvas

SIMPL programs are organized into a system tree on the left and a logic canvas on the right.

System tree — Lists all hardware in the system: the control processor, touchpanels, network devices, RS-232 devices, relay modules, etc. Each device is added by selecting it from Crestron's device database, which assigns the correct join numbers, serial ports, and I/O.

Logic canvas (Program View) — The working area where logic symbols are placed and connected. Symbols are organized into pages for readability — common pages include System Startup, Display Control, Audio Control, Source Routing, Conferencing. Pages are organizational only; all signal connections work across pages.

Signal List — A searchable list of all signals defined in the program. Essential for finding where a signal is driven or consumed. Accessible via View → Signal List. Indispensable when debugging large programs.

Joins

Joins are the numbered connection points between the control processor and a touchpanel (or other controllable device). Every button, text field, slider, and indicator on a touchpanel has a join number. The SIMPL program drives or reads these join numbers to control panel behavior.

Join Types

The same join number can carry a signal in both directions for different purposes: digital join 1 from the panel is the button press; digital join 1 to the panel is the LED feedback for that button.

Touchpanel Join Assignment

In VT Pro-e (3-Series panels) or XPANEL Designer (4-Series), every interactive element on the panel is assigned a join number by the programmer. The SIMPL program uses those same join numbers to communicate with the panel. A button at digital join 101 pressing sends a digital high on join 101 from the panel; the SIMPL symbol at join 101 receives that high and takes action (sending an RS-232 command, routing a source, etc.). The LED for that button turns on when the SIMPL program drives join 101 back high as feedback.

Organizing join numbers into blocks by function — buttons 1–50, feedback 51–100, source names serial 1–20 — makes programs easier to follow and document.

Logic Symbols

SIMPL includes hundreds of built-in logic symbols covering standard programming needs. Key categories:

Basic Logic

• AND, OR, NOT, XOR — Boolean logic gates for combining digital signals
• Latch (S/R Flip-Flop) — Set/Reset latch; Set input drives output high and holds it; Reset drives it low. Used for toggle logic: one press turns on, another turns off.
• One Shot — Emits a brief pulse (one processor cycle) when input goes high. Used to generate trigger pulses from button press signals.
• Toggle — Alternates output state on each leading edge of input. Classic use: single-button on/off toggle.
• Buffer — Passes a signal through unchanged; useful for organizing signal routing across long distances on the canvas.

Timing

• Delay — Holds output high for a defined duration after input goes low. Used to keep a relay closed for a minimum time.
• Pulse — Emits a high pulse of defined duration when input goes high. Used for momentary relay closure.
• Time of Day — Scheduled digital output based on real-time clock. Used for scheduled room power-on, auto-shutdown at end of day.

Analog Operations

• Analog Ramp — Increments or decrements an analog value at a defined rate while the ramp input is held. Used for volume up/down buttons.
• Analog Initialize — Sets an analog signal to a defined value on program start or reset. Used to set default volume levels.
• Scale — Maps an analog input range to a different output range. Used when a device uses 0–100% but the control system uses 0–65535.
• Analog Compare — Outputs a digital high when an analog value crosses a threshold. Used for occupancy detection (sensor value > threshold → room occupied).

String Operations

• String Formatter — Assembles a serial string from static text and signal values. Used to build RS-232 commands with embedded parameters: \x02VOLS{vol_level}\x03.
• Serial Deparser — Extracts values from a received serial string using delimiters or fixed-width parsing. Used to parse RS-232 status responses.
• Buffer — Accumulates incoming serial data; emits assembled string when a delimiter is detected. Essential for RS-232 feedback parsing.

Device Modules

Device modules are pre-built SIMPL sub-programs for controlling specific third-party devices. Crestron and manufacturers publish modules for thousands of AV devices — displays, projectors, amplifiers, cameras, DSPs. A module encapsulates the RS-232 or IP protocol details and exposes clean digital/analog/serial signals at its interface.

Adding a device module:

1. In the SIMPL System Tree, add the physical device (RS-232 port, TCP/IP client, etc.)
2. In the Logic View, drag in the module from the Crestron library or a manufacturer-provided .usp file
3. Connect the module's COM port signal to the physical port signal in the System Tree
4. Wire the module's control signals (Power On, Power Off, Input Select) to your touchpanel join signals

A good device module dramatically reduces programming time — a Sony projector module exposes Power_On, Power_Off, Input_HDMI1, Power_FB signals that are simply connected to panel joins. No RS-232 command knowledge required.

Module version management: Device modules are firmware-specific. A module written for a display's firmware 3.x may not parse responses correctly on firmware 4.x. When a device's behavior changes after a firmware update, check for an updated module version from the manufacturer or Crestron before debugging protocol details.

SIMPL+ Modules

SIMPL+ is a text-based programming language used to write custom SIMPL modules for devices without published drivers or for custom logic. SIMPL+ modules compile to binary and appear as standard modules in SIMPL Windows. SIMPL+ supports string manipulation, math operations, event-driven functions, and IP/RS-232 communication.

SIMPL+ is distinct from SIMPL# Pro — SIMPL+ is older, runs on both 3-Series and 4-Series, and is used for module-level logic. SIMPL# Pro (see control-systems/crestron-simpl-sharp) is the newer environment for full program-level C# development on 4-Series.

RS-232 Configuration

RS-232 devices require matching communication parameters between the SIMPL program and the device.

SIMPL RS-232 setup:

1. In the System Tree, select the control processor and find its COM ports (COM1, COM2, etc.)
2. Right-click the COM port → Properties → set baud rate, data bits, parity, stop bits, flow control
3. Parameters must match the device spec exactly — most AV displays: 9600 8N1, no flow control
4. In Logic View, connect RS232_TX$ (output) and RS232_RX$ (input) signals to the device module

Terminator characters: RS-232 commands typically terminate with \r (carriage return, 0x0D), \n (line feed, 0x0A), or \r\n. Extron SIS: \r only. Most displays: \r\n. Check the device's communication protocol document — an incorrect terminator is the most common reason commands are not received.

Rx Buffer accumulation: Responses from devices arrive as a stream of bytes, not complete strings. Always connect the COM port Rx output to a SIMPL+ buffer module or use a Serial Buffer symbol before parsing. Attempting to parse a partial response causes failures.

IP Control

IP-controlled devices connect via the TCP/IP Client symbol in SIMPL.

TCP/IP Client configuration:

1. In System Tree, add a TCP/IP Client device under the control processor
2. Set the target IP address and port number (configurable or fixed at commissioning)
3. Connect the client's TX$ and RX$ signals to the device module
4. The client's Connect digital input initiates the TCP connection; Connected_FB goes high when connected

Most device modules handle the TCP connection management internally. For custom SIMPL+ modules, implement a reconnect timer: if Connected_FB drops low, wait 5 seconds and drive Connect high again. Devices that close the TCP connection after each command (HTTP-style) need a connect-send-disconnect pattern.

UDP: Some devices use UDP instead of TCP. SIMPL includes a UDP/IP Server symbol. Unlike TCP, UDP is connectionless — no Connect input; data is sent and received immediately. Common for AMX/Extron discovery protocols, some matrix switchers.

Touchpanel Integration

Touchpanels connect to the control processor via Crestron's proprietary CIP (Crestron IP) protocol over Ethernet, or via Cresnet (RS-485 bus) for wired panels.

IP-connected panels (TSW series): The panel is configured with the processor's IP address and IP ID (a unique hex identifier, typically 03–FE, that distinguishes multiple panels). In SIMPL, the panel appears in the System Tree as a Touchpanel device with the same IP ID. The join range is configured per panel.

Cresnet panels (older installations): Connected via 4-conductor Cresnet bus (power + data). Each Cresnet device has a unique Cresnet ID (01–FE). No IP configuration needed on the panel — just assign the Cresnet ID via the panel's menu. Maximum bus length: 1000 ft at 24V; 4000 ft with a Cresnet Hub/Repeater (CNXHUB).

Multiple panels, same join range: Multiple touchpanels in the same room can share the same join space. A press on panel 1 join 5 and a press on panel 2 join 5 both drive the same Source_HDMI_Select signal. Feedback to join 5 goes to both panels simultaneously. This is the standard design for rooms with a wall panel and a portable tablet.

Crestron Toolbox — Debugging and Diagnostics

Crestron Toolbox is the diagnostics and management utility for Crestron hardware. Essential for field work.

Key Toolbox Functions

System Info — Shows processor model, firmware version, IP address, MAC address, memory usage, uptime, and program status (running/stopped). First stop for any troubleshooting visit.

Text Console — A terminal connection to the processor's command-line interface. Directly enters SIMPL program commands, reads responses, and queries system state. Essential debugging tool.

Useful Text Console commands:

PROG STATUS          # Show running programs and their states
PROG LIST            # List all uploaded programs
RSTST                # Restart the control system (soft reset)
IPCONFIG             # Show network configuration
ERR                  # Display error log

Signal List / SIMPL Debugger — When the SIMPL program is running, the debugger shows real-time signal values. Filter by signal name to watch a specific signal change as buttons are pressed. This is the fastest way to confirm a signal is being driven correctly or identify where logic is failing. Access via: Tools → SIMPL Debugger.

Port Monitor — Monitors RS-232 or IP traffic in real time — shows exact bytes sent and received. Invaluable for verifying that RS-232 commands are being transmitted correctly and that device responses match expectations. If a display is not responding to power-on commands, Port Monitor confirms whether the command was sent and what (if anything) came back.

Firmware Update — Crestron Toolbox handles firmware updates for processors, touchpanels, and network devices. Always verify firmware compatibility before updating; some updates require SIMPL program recompilation.

X-Panel — A software touchpanel that renders any uploaded touchpanel project in a window on the PC. Allows testing panel behavior without physical hardware present. Useful for demonstrating programs before installation.

Program Upload and Execution

Compiling: SIMPL programs are compiled via Build → Compile (F7). Compilation checks signal connections, device compatibility, and outputs a .spz compiled program file.

Uploading: Connect Toolbox to the processor (IP address required) → File → Send to Control System → select the .spz file. The processor loads and runs the new program. Most processors do not require a reboot for program updates — the new program replaces the running one.

Startup behavior: Control processors execute the SIMPL program continuously in a loop. On first power-up or after a program update, a startup macro runs — this is where initial states are set (default volume, display power off, etc.). The GLBL_START_FB signal (global start feedback) goes high once on program start; use it to trigger initialization logic.

Program storage: Programs are stored in non-volatile flash memory. The processor retains and runs the last uploaded program through power cycles.

Common Pitfalls

• Signal name typo creates unconnected signal. SIMPL connects symbols by matching signal names exactly, including case. Display_Power_On and display_power_on are two different signals. If a button press has no effect, check the Signal List to verify the signal has both a driver (source) and at least one consumer (destination). Signals with only one connection are shown in grey — a visual indicator of an orphaned signal.

• RS-232 baud rate or terminator mismatch. The most common RS-232 failure. If a display does not respond to SIMPL commands, verify in Port Monitor that the command was actually sent (character for character), then verify the baud rate and terminator match the device spec. Sending \x02POWR1\x03\r\n when the device expects \x02POWR1\x03\r causes silent failure.

• No RS-232 Rx buffer accumulation. Attempting to parse the RS-232 Rx signal directly without a buffer causes intermittent failures when the response arrives in multiple packets. Always buffer Rx before parsing, even for short responses. This is especially critical for IP-based devices where TCP segmentation is unpredictable.

• Join numbers not matching between SIMPL and VT Pro-e/XPANEL. The SIMPL program drives digital join 50 for display power feedback; the touchpanel button LED is assigned to digital join 51. The button LED never illuminates. Maintaining a join map spreadsheet and keeping it synchronized with both tools is the only reliable prevention.

• IP ID conflict between panels. Two touchpanels configured with the same IP ID on the same processor cause both panels to malfunction intermittently — they fight over the control connection. Assign unique IP IDs (e.g., panel 1 = 0x03, panel 2 = 0x04) and document the assignments. Symptoms of IP ID conflict: panel spontaneously disconnects and reconnects, joins fire unpredictably.

• 3-Series program runs on 4-Series with unexpected behavior. Some 3-Series SIMPL symbols behave differently on 4-Series firmware or have no 4-Series equivalent. After recompiling a 3-Series program for 4-Series, test every function — do not assume equivalence. Known differences include timing behavior of One Shot symbols and some serial processing symbols.