Return to Data Core

Crestron 3-Series SIMPL# Module Pattern With a SIMPL+ Wrapper

2026-05-24
Crestron module workflow thumbnail showing AI-assisted module logic connected to code and AV controls

Crestron 3-Series SIMPL# Module Pattern With a SIMPL+ Wrapper

This note documents a reusable pattern for building Crestron 3-Series SIMPL# modules that can be called from SIMPL Windows through a SIMPL+ wrapper.

The pattern came out of the PTZOptics G3 camera module build, where the final 3-Series module compiled cleanly with the SIMPL+ compiler:

Total Error(s): 0
Total Warning(s): 0

The purpose of this article is to leave a clear trail for future AV programmers, AI coding assistants, and project teams who need to build a similar module without rediscovering the same Crestron toolchain constraints.

The Basic Shape

The working structure is:

DeviceDriver.cs
DeviceDriver.clz
DeviceModule.usp
DeviceModule.ush
VS2008/
  DeviceDriver/
    DeviceDriver.sln
    DeviceDriver.csproj
    DeviceDriver.cs

The responsibilities are split cleanly:

  • DeviceDriver.cs: SIMPL# source code
  • DeviceDriver.clz: compiled SIMPL# library archive
  • DeviceModule.usp: editable SIMPL+ wrapper
  • DeviceModule.ush: compiled SIMPL+ module output
  • VS2008/DeviceDriver/*.sln: Visual Studio 2008 SIMPL# project

The SIMPL+ wrapper stays thin. The heavier logic lives in SIMPL#.

The Wrapper Reference Rule

The SIMPL+ wrapper must reference the SIMPL# library by the CLZ base filename:

#USER_SIMPLSHARP_LIBRARY "DeviceDriver"

That means the compiled library file must be named:

DeviceDriver.clz

If the CLZ is renamed, the #USER_SIMPLSHARP_LIBRARY line must be updated to match. This small naming rule is easy to miss, but it is one of the first things to verify when a wrapper cannot see the library.

Why Visual Studio 2008 Still Matters

Modern Crestron SIMPL# workflows can be useful for newer targets, but they do not always produce a library archive that validates cleanly for 3-Series SIMPL+ builds.

For the PTZOptics module, the reliable 3-Series path used:

  • Visual Studio 2008 Professional
  • Visual Studio 2008 SP1
  • Crestron SIMPL# Components Program 2.000.0058.01
  • Crestron SIMPL Windows
  • SPlusCC.exe

That older toolchain matters because the processor target is older. A C# library can compile successfully and still fail the 3-Series SIMPL# archive verifier if it was produced through the wrong path.

What To Put In SIMPL#

The SIMPL# driver is the right place for logic that would be clumsy or fragile in SIMPL+.

Good SIMPL# responsibilities include:

  • TCP socket handling
  • HTTP request formatting
  • Response parsing
  • Timeout handling
  • Command state
  • Last-response tracking
  • Authentication handling, when the supported API surface allows it

For constrained 3-Series modules, keep dependencies minimal and prefer Crestron SIMPL# APIs when possible.

In the PTZOptics G3 module, raw HTTP requests were sent with:

Crestron.SimplSharp.CrestronSockets.TCPClient

That worked better for the 3-Series archive path than using the higher-level .NET HttpWebRequest API.

What To Keep In SIMPL+

The SIMPL+ wrapper should mainly act as the bridge between SIMPL Windows signals and the SIMPL# class.

Good SIMPL+ responsibilities include:

  • Digital input declarations
  • Analog input declarations
  • Serial input declarations
  • Digital feedback declarations
  • Analog feedback declarations
  • Serial feedback declarations
  • Configuration parameters
  • Simple calls into public SIMPL# methods
  • Routing SIMPL# feedback back to SIMPL Windows

This keeps the wrapper readable and makes it easier to reuse the same pattern for other devices.

Build Process

The practical build loop is:

  1. Edit the SIMPL# driver source.
  2. Build the SIMPL# library in Visual Studio 2008.
  3. Copy the generated .clz beside the .usp wrapper.
  4. Compile the SIMPL+ wrapper for 3-Series.
  5. Verify the compiler result.

The SIMPL+ compile command looks like this:

SPlusCC.exe \rebuild ".\DeviceModule.usp" \target series3

The build gate should be:

Total Error(s): 0
Total Warning(s): 0

Anything less than that should stay in development.

3-Series Safety Rules

When adapting this pattern for another device, follow these rules:

  1. Keep the SIMPL# dependency surface small.
  2. Avoid modern C# syntax that Visual Studio 2008 cannot compile.
  3. Avoid APIs that may compile as a DLL but fail 3-Series CLZ validation.
  4. Build the CLZ through the Visual Studio 2008 Crestron SIMPL# plugin.
  5. Keep the SIMPL+ wrapper thin.
  6. Match the #USER_SIMPLSHARP_LIBRARY name to the CLZ filename.
  7. Compile the wrapper with \target series3.
  8. Separate compile success from live hardware validation.

That last rule is important. A clean compile proves the module is structurally buildable. It does not prove the device was controlled successfully from a real processor.

A Useful Prompt For Future AI Work

When handing this pattern to an AI assistant, use a prompt like this:

Create or modify a Crestron 3-Series SIMPL# module using a thin SIMPL+ wrapper.
Build the SIMPL# CLZ through the Visual Studio 2008 Crestron SIMPL# plugin.
Keep the #USER_SIMPLSHARP_LIBRARY name matched to the CLZ filename.
Prefer Crestron.SimplSharp APIs and a small dependency surface.
Compile the SIMPL+ wrapper with SPlusCC.exe target series3.
Report compile results separately from real hardware validation.

This gives the assistant the constraints that matter before it starts writing code.

Why This Is Worth Documenting

Most module work is not only about the device protocol. It is about the toolchain, the target processor family, the wrapper boundary, and the exact build artifacts that SIMPL Windows expects.

Documenting the working pattern means the next module can start from a proven shape:

  • SIMPL# for the device logic
  • SIMPL+ for the SIMPL Windows bridge
  • VS2008 for 3-Series CLZ generation
  • SPlusCC.exe as the final build gate
  • Clear notes about what has and has not been hardware-tested

That is the difference between a one-off module and a reusable AV engineering workflow.