DSC Keybus Interface

This library directly interfaces Arduino, esp8266, esp32, and esp32-s2 microcontrollers to DSC PowerSeries and Classic series security systems for integration with home automation, remote control as a virtual keypad, notifications on alarm events, unlocking installer codes, and emulating DSC panels to use DSC keypads as general purpose input devices.

This enables existing DSC security system installations to retain the features and reliability of a hardwired system while integrating with modern devices and software for under $5USD in components.

The built-in examples can be used as-is or as a base to adapt to other uses:

• Home automation integration: Home Assistant, Apple HomeKit & Siri, Google Home, OpenHAB, Athom Homey
• Remote control: Web interface, Blynk mobile app, Telegram bot (with remote arming/disarming via chat)
• Notifications: Pushover, PushBullet, Pushsafer, Twilio SMS, TinyGSM SMS, E-mail
• Keypad interface: Emulates a DSC panel to connect DSC keypads as physical input devices for any general purpose, without a DSC panel.
• Installer code unlocking: Automatic code search to unlock panels with unknown installer codes

Example integrations:

• Apple Home & Siri:
  
• Home Assistant:
  
• OpenHAB MQTT:
  
• Blynk app virtual keypad:
  
• Web virtual keypad:
  
• Telegram bot:
  

Quick start

1. Install the DSC Keybus Interface library:
   • Arduino IDE: Search for DSC in the Library Manager - Sketch > Include Library > Manage Libraries
     
   • PlatformIO IDE: Search for DSC in the PlatformIO Library Registry
     
   • PlatformIO CLI: platformio lib install "dscKeybusInterface"
   • Alternatively, git clone or download the repo .zip to the Arduino/PlatformIO library directory to keep track of the latest changes.
2. Select, configure, and upload one of the example sketches to the microcontroller:
   
3. Connect the microcontroller to the DSC Keybus per the wiring diagram with the appropriate resistors (and a transistor if you'd like to control the system).

Why?

I Had: A DSC security system not being monitored by a third-party service.
I Wanted: Notification if the alarm triggered.

I was interested in finding a solution that directly accessed the pair of data lines that DSC uses for their proprietary Keybus protocol to send data between the panel, keypads, and other modules (instead of using the DSC IT-100 serial module). Tapping into the data lines is an ideal task for a microcontroller and also presented an opportunity to work with the Arduino and FreeRTOS (via esp-open-rtos) platforms.

While there has been excellent discussion about the DSC Keybus protocol and several existing projects, there were a few issues that remained unsolved:

• Error-prone Keybus data capture.
• Limited data decoding - there was good progress for armed/disarmed states and partial zone status for a single partition, but otherwise most of the data was undecoded (notably missing the alarm triggered state).
• Read-only - unable to control the Keybus to act as a virtual keypad.
• No implementations to do useful work with the data.

This library uses a combination of hardware and timer interrupts to accurately capture Keybus data, and has lead to reverse engineering much of the Keybus protocol.

Features

• Monitor the status of all partitions:
  • Alarm triggered, armed/disarmed, entry/exit delay, fire triggered, keypad panic keys
• Monitor zones status:
  • Zones open/closed, zones in alarm
• Monitor system status:
  • Ready, trouble, AC power, battery
• Monitor PGM outputs 1-14 status
• Virtual keypad:
  • Write keys to the panel for all partitions
  • Trigger panel command outputs
• Keypad interface:
  • Emulates a DSC panel to use DSC PowerSeries and Classic series keypads as physical input devices for any general purpose, without needing a DSC panel.
• Panel time - retrieve current panel date/time and set a new date/time (including an example with NTP sync)
• Panel installer code unlocking - determine the 4-digit panel installer code
• Virtual zone expander - the expander branch can emulate a DSC zone expander module to add zones to the security system that are handled by the microcontroller - thanks to Dilbert66 for this contribution!
• Direct Keybus interface:
  • Does not require the DSC IT-100 serial interface.
• Designed for reliable data decoding and performance:
  • Hardware GPIO pin interrupts and timer interrupts for accurate data capture timing
  • Data buffering: helps prevent lost Keybus data if the sketch is busy
  • Extensive data decoding: the majority of Keybus data as seen in the DSC IT-100 Data Interface developer's guide has been reverse engineered and documented in src/dscKeybusPrintData.cpp.
  • Non-blocking code: Allows sketches to run as quickly as possible without using delay or delayMicroseconds
• Supported security systems:
  • DSC PowerSeries - all panels are supported, tested with: PC585, PC1555MX, PC1565, PC1565-2P, PC5005, PC5010, PC5015, PC5020, PC1616, PC1808, PC1832, PC1864
  • DSC Classic series: PC1500, PC1550, PC2550
    • Requires configuring the panel through *8 programming to enable PC16-OUT: section 19, option 4.
    • PC2500 and PC3000 are untested, post an issue if you're able to test these panels.
  • Rebranded DSC PowerSeries (such as some ADT systems) should also work with this interface.
• Unsupported security systems:
  • DSC Alexor (PC9155) is all wireless and does not have an accessible Keybus interface.
  • DSC Neo series use a higher speed encrypted data protocol (Corbus) that is not currently possible to support.
  • Other brands (that are not rebranded DSC systems) use different protocols and are not supported.
    • For Honeywell Ademco Vista 15P/20P, see Dilbert66's esphome-vistaECP project
    • For Paradox systems, see liaan's paradox-esp8266 project
• Supported microcontrollers:
  • Arduino:
    • Boards: Uno, Mega, Leonardo, Mini, Micro, Nano, Pro, Pro Mini
    • ATmega328P, ATmega2560, and ATmega32U4-based boards at 16Mhz
  • esp8266:
    • Development boards: NodeMCU v2 or v3, Wemos D1 Mini, etc.
    • Includes Arduino framework support and WiFi for ~$3USD shipped.
  • esp32:
    • Development boards: NodeMCU ESP-32S, Doit ESP32 Devkit v1, Wemos Lolin D32, etc.
    • Includes Arduino framework support (v2.0.2 or newer required), dual cores, WiFi, and Bluetooth for ~$5USD shipped.
  • esp32-s2:
    • Includes Arduino framework support (v2.0.2 or newer required) and WiFi.
• Possible features (PRs welcome!):
  • DSC IT-100 emulation
  • Unlock 6-digit installer codes

Release notes

• 3.0
  • New: DSC Classic series panel support: PC1500, PC1550, PC2550
  • New: KeypadInterface and KeypadInterface-MQTT example sketches - emulate a DSC panel to connect DSC PowerSeries and Classic keypads as physical input devices for any general purpose, without needing a DSC panel.
  • New: HomeKit-HomeSpan example sketch (esp32) - integrate directly with Apple HomeKit as a native standalone accessory using HomeSpan
  • New: Pushover and [Pushsafer](htt