# AI Reference: Crestron SIMPL Windows, GitHub, and AI Module Workflow

Source article: https://avedgetech.com/wiki/crestron-simpl-windows-github-ai-module-workflow/

This Markdown note is intended for AI assistants, AV programmers, and future automation workflows that need to understand the practical method described in the AV Edge Tech article.

## Purpose

Use GitHub as the source of truth for Crestron SIMPL Windows module work, while using an AI coding assistant to help create, revise, compile, document, and maintain SIMPL+ and SIMPL Windows module logic.

The important point is that AI should not only generate code. A useful agent workflow should operate inside the workstation that has the Crestron toolchain installed, run the SIMPL+ compiler, read compiler output, fix the source, and repeat until the module compiles cleanly.

## Core Workflow

1. Store editable SIMPL+ source, module documentation, examples, and compiled artifacts in a GitHub repository.
2. Use SIMPL Windows as the integration environment for real control system projects.
3. Use AI to scaffold, refactor, document, and review focused Crestron modules.
4. Let the AI invoke the installed Crestron SIMPL+ compiler where possible.
5. Treat compiler output as the truth source, not the AI response.
6. Iterate until the module compiles with 0 warnings and 0 errors.
7. Commit the clean source and useful compiled artifacts back to GitHub.
8. Test the module in SIMPL Windows and then against the real device, processor, or controlled test environment.

## Suggested Repository Layout

```text
crestron-modules/
  modules/
    device-or-feature-name/
      src/
        module-name.usp
      compiled/
        module-name.ush
      docs/
        README.md
      examples/
        module-demo.smw
  shared/
    parsing/
    serial-helpers/
  README.md
```

Keep editable source in the repo. Compiled files can be included when they are useful for deployment, but they should not replace the source.

## AI Agent Instructions

When helping with this workflow, an AI assistant should:

- Inspect the existing repo structure before inventing a new pattern.
- Preserve existing SIMPL Windows signal names unless a change is explicitly requested.
- Keep module changes focused and small enough to review.
- Prefer readable SIMPL+ over clever logic that is hard to troubleshoot onsite.
- Run the SIMPL+ compiler if the local toolchain is available.
- Parse compiler warnings and errors, then revise the source.
- Repeat compile and fix cycles until the compiler reports 0 warnings and 0 errors.
- Update the module README with supported devices, signal lists, compile notes, and field notes.
- Avoid calling a module complete until it has compiled cleanly and has a test plan for the real device.

## Good AI Targets

AI is most useful for focused module tasks such as:

- SIMPL+ protocol parsers
- Serial command formatting
- TCP socket send and receive handling
- Feedback parsing
- API wrapper logic
- Signal contract cleanup
- Module README generation
- Compile-error repair loops
- Converting field notes into permanent documentation

AI should not be treated as a substitute for final Crestron compiler validation, SIMPL Windows integration review, or real device testing.

## Example Prompt

```text
Review this Crestron SIMPL Windows module repository.

Keep GitHub as the source of truth. Preserve the existing module structure unless it is clearly broken.

For the target module:
- review the SIMPL+ source
- keep signal names stable where possible
- clean up protocol parsing and feedback mapping
- update the README with signals, compile notes, and field notes
- run the Crestron SIMPL+ compiler if available
- fix all compiler warnings and errors
- repeat until the compiler reports 0 warnings and 0 errors

Do not mark the module complete until the compiled output is clean and the remaining hardware test steps are documented.
```

## Validation Checklist

Before using an AI-assisted Crestron module in a project:

- SIMPL+ source is committed to GitHub.
- Compiled artifact is included when useful for deployment.
- Compiler result is documented.
- Compile result is 0 warnings and 0 errors.
- SIMPL Windows signal names match the expected program wiring.
- Serial strings, TCP payloads, or API requests match the manufacturer protocol.
- Receive buffers handle partial frames and multiple frames where relevant.
- Offline behavior is safe and documented.
- Hardware or simulator testing remains a required final step.

## Key Takeaway

The reliable workflow is not simply "AI writes Crestron code." The reliable workflow is:

```text
GitHub source -> AI edit -> Crestron compiler -> AI repair loop -> clean artifact -> SIMPL Windows integration -> field test -> documented commit
```

That loop gives Crestron SIMPL Windows module work a modern development memory while still respecting the realities of the Crestron toolchain and field deployment.