DRACONi Automation
The Manual!
For Version Alpha0.05
http://www.draconidigital.com/draconiautomation


PLEASE NOTE!!!

This is alpha-level software. While this code is based on software that has been in use for years, this code itself is new. This may mean it's broken. We've tried to make an effort to ensure that it all works, but we also guarantee there will be bugs, much to our chagrin.

In addition, this manual was written quickly for release, so it may be lacking as well. While we've tried to include as much information as possible, there is probably much more that needs to be added.


Table of Contents

  • Introduction
  • Requirements
  • Setup
  • Using DRACONi Automation
  • Adding Modules
  • Support

  • Introduction

    DRACONi Automation aims to be a home automation and digital entertainment control package. It's designed to be modular, meaning new kinds of functionality can be added easily.

    Currently, DRACONi Automation can interface with the following:
  • CM11A/CK11A X10 ActiveHome Home Automation Controller
  • Applied Digital (ADI) Ocelot/Leopard/Leopard II Home Automation Controllers
  • XMMS Music Player for web-based jukebox control
  • Festival Speech Synthesis (Text To Speech) Software for Linux
  • Infrared Control GUI (via ADI Ocelot/Leopard)
  • DRACONi Automation offers the following features:
  • User based system complete with per-user security permissions (you can restrict certain users to only user certain parts of the system)
  • Multiple interfaces
  • HTML - for most standard web browsers
  • mobile HTML - for mobile devices with smaller screens such as PDAs and larger cell-phones that can read HTML, but have
  • xHTML Basic/WAP 2.0 - for mobile devices such as cell phones with very small screens and low bandwidth
  • User-definable macro system. Macros can be created which can control nearly any module in the system! You could create a 'movie scene' macro which could dim the lights, play some intro music while the movie is loading, and even make an annoucement via text-to-speech!
  • Modular design. Functionality can be extended/customized via easily added modules. Plus, modules can be designed so as to be a part of the macro system!
  • Other features on the way are:
  • Anything we can get our hands on to control!
  • "Skinnable" themes
  • DRACONi Automation is a combination of two pieces of software that have been developed by Joe Thielen over the years. The first is XMMS-Control, which was developed to be a web-based interface to the XMMS MP3 player for Linux. While XMMS-Control is a great stand-alone jukebox program, it's integration into DRACONi Automation is a big feature! The second is a piece of software is code-named Id. This software has been developed over the past few years to explore the interfacing capabilities of the Applied Digital Ocelot/Leopard and X10 CM11A. The software has been kept in-house until it's integreation into DRACONi Automation!

    The decision to release DRACONi Automation under the GPL, free to the community, was made by Joe Thielen and Rick Mottmiller (both of DRACONi Digital). This is DRACONi Digital's way of saying THANK YOU to those who've given us the GPL, Linux, Apache, Mozilla, PHP, MySQL, XMMS, and so many other wonderful pieces of freely available software!

    Because DRACONi Digital plans on making money by selling equipment and service used with DRACONi Automation, free support will be limited. However, DRACONi Digital has a section on their forum specifically dedicated for DRACONi Automation! In addition, any community contributions (bug fixes, new modules/features, etc...) will be posted on the DRACONi Automation website (hosted courtesy of DRACONi Digital!)

    Requirements

    DRACONi Automation has the following requirements:
  • A Linux system with PHP installed (including a PHP-capable web server, i.e. Apache) and the MySQL database.
  • FOR MUSIC/JUKEBOX CONTROL:
  • XMMS (installed or available on most major Linux distributions) or NOXMMS (a stripped down version of XMMS that can run in the background WITHOUT A GUI!) for MP3/media jukebox control
  • XMMS-SHELL (typically installed with XMMS) for interfacing with XMMS
  • FOR APPLIED DIGITAL OCELOT/LEOPARD CONTROL:
  • A serial port to connect to the ADI Ocelot/Leopard (if no serial ports are available, a linux compatible USB-to-Serial adapter can be used, we've had good experience with the Belkin model based on the pl2303 chipset)
  • FOR X10 CM11A CONTROL:
  • HEYU for interfacing with the CM11A X10 Controller
  • A serial port to connect to the CM11A (if no serial ports are available, a linux compatible USB-to-Serial adapter can be used, we've had good experience with the Belkin model based on the pl2303 chipset)
  • FOR FESTIVAL TEXT TO SPEECH:
  • The Festival Speech Synthesis Software
  • FOR INFRARED CONTROL:
  • An ADI Ocelot or ADI Leopard with the IR adaptor. Currently, only the IR out on the Ocelot/Leopard itself is supported. Support is planned for the ADI SECU16-IR IR Output module

  • Setup

    To install DRACONi Automation:

  • Place the distribution file (the .tar.gz file) into your web server directory (typically '/var/www/html') and uncompress it (typically 'tar -xzvf FILE.tar.gz'). It will uncompress into a directory named 'da'.
  • Run the 'fix_links' script.
  • Initialize the database tables DRACONi Automation will need:
  • First, edit the 'DB INFO' section in the 'vars.inc' file. Supply the name of the database you want DRACONi Automation to use ('$iddb_name', defaults to 'id'), the username for MySQL ('$iddb_user', default is 'root'), the database password ('$iddb_pass', default is blank), and the host the database resides on ('$iddb_host', default is 'localhost').
  • Second, in the 'DB/mysql' subdirectory, run the script called 'RELOAD'. This command will dump any current database named 'id' (which is the name of the database DRACONi Automation uses by default). It will then load all of the default data. This requires that the 'mysql' command be in the path and that you are capable of creating databases. You may then need to edit the 'vars.inc' file and modify the settings in the 'DB INFO' section to match your database configuration.
  • You should now be able to log into DRACONi Automation. However, to do anything useful, you will need to setup the various modules the system uses. See below for more information.
  • If you plan to use the XMMS jukebox functions of DRACONi Automation, you will need to do the following:
  • Have XMMS (or NOXMMS) installed and running
  • Have XMMS-Shell installed and running.
  • For Mandrake Linux 10 (and possibly other Linux distributions), additional steps may be required to ensure the web server can write to the XMMS controller file.
  • FOR NOXMMS: Please see the included 'start_noxmms' file. If you place this file in /usr/bin and then execute this file in your /etc/rc.d/rc.local startup file, this should start NOXMMS and fix any problems. If you also place a link to this file in your /etc/cron.hourly directory, this will help insure you have a fairly redundant system. In the case that NOXMMS crashes, this will try and re-start it every hour on the hour.

  • If you plan on using the Applied Digital Ocelot/Leopard home automation controller functions of DRACONi Automation, you will need to do the following:
  • Ensure that the port hooked to the Ocelot/Leopard is writable by the webserver. To help, see the included 'fix_serial' script. If you're using the first serial port on the sytstem (/dev/ttyS0 in most Linux distributions) you can use this script as is. If you're using a different port (or using a USB-Serial converter), you'll have to edit it to specfy which port you're using. You may also want to place a link to this script into your /etc/cron.hourly directory so it runs every hour. Many newer versions of Linux change the permissions of this file upon reboot, so this script may need to be run immediately after reboot also. We've tried to place this script into the '/etc/rc.d/rc.local startup script, but with only limited success. Another approach may be to have this script run every minute via cron.
  • If you plan on using the X10 CM11A home automation controller functions of DRACONi Automation, you will need to do the following:
  • Ensure that the HEYU program is installed and working with your CM11A. To test this, make sure your CM11A is plugged into the computer and issue the following command from the command-line: 'heyu turn A1 on'. This will turn the device with the housecode A and unitcode 1 on. If you have no device set at A1, you will need to change the above command. If this command works, then you should be able to use this program with DRACONi Automation. If it does not work from the command line, then it is not going to work with DRACONi Automation. If it does work from the command line, but does not work with DRACONi Automation, you may have to give it special permission to be run from the webserver. To do this, use the command 'chmod a+s heyu' in the directory that heyu is in.
  • Specify the location of the heyu command in the 'vars.inc' file in the AUTOMATION - CONTROL PANEL section. The default is '/usr/local/bin/heyu'
  • If you plan on using the Festival Speech Synthesis Software, you will need to do the following:
  • Specify the location of the festival command in the 'vars.inc' file in the FESTIVAL - CONTROL PANEL section. The default is '/usr/bin/festival'

  • Using DRACONi Automation

    This section will be filled out more as time goes on, and may be put into a separate document in the future.

    IMPORTANT NOTE: The first time you access DRACONi Automation using a device other than a standard web browser (i.e., PDA or cell phone), you may need to let DRACONi Automation know what kind of device and interface you wish to use with that device. There is an easy way to do this. Simply point your devices browser at one of the following address to set this up. Do not worry, once it's defined, it can be easily changed to another interface by simply trying a different address below:

    InterfaceDescriptionAddress
    htmlStandard HTML - For most computer browsers/html
    mhtmlMobile HTML - For most PDAs and larger cell phones/mhtml
    xhtmlxHTML Basic/WAP2.0 - For smaller PDAs and small cell phones/xhtml

    For instance, if this is the first time you're going to use DRACONi Automation on your cell phone, you have your machine set up to be accessible from the web (with the domain 'bobskewlhouse.com'), and DRACONi Automation is set up in the 'da' directory of your webserver, then you would go to the address:

    http://www.bobskewlhouse.com/da/xhtml

    It should tell you that your device is now set up for that interface. Then, every time you go to DRACONi Automation from that device (or a device with that same browser), it will take you directly to that interface!!! From that point on, you would simply access DRACONi Automation directly, i.e.:

    http://www.bobskewlhouse.com/da


    Adding Modules

    For more information on adding modules to DRACONi Automation, please see the separate Module Hacking document!


    Support

    As mentioned in the introduction, DRACONi Automation is made available under the GPL courtesy of DRACONi Digital as a way of saying THANK YOU to the free software community. Limited free support will be available as time permits. Please do not take this to mean we are just dumping this software out there. We are planning on actively maintaining DRACONi Automation and adding features, and we look forward to community participation and interaction!

    Primary Free Support for DRACONi Automation: DRACONi Digital Forum

    Also check out the DRACONi Automation Webpage

    If you're interested in paid support or would like a custom built system using DRACONi Automation, please feel free to contact DRACONi Digital!!!


    Joe Thielen
    08/09/2004