/*       Copyright (c) Eric Ledoux.  All rights reserved.       */
/* See http://www.dwell.net/terms for code sharing information. */

// Cm11.cs
//
// Implements the DwellNet.Cm11 class.
//

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics;
using System.Drawing;
using System.IO.Ports;
using System.Threading;
using System.Text;
using System.Text.RegularExpressions;
using DwellNet;
using DwellNet.Properties;

namespace DwellNet
{

using (Cm11 cm11 = new Cm11())
{
    cm11.Open("COM1");
    cm11.Execute("A1 On");
    cm11.WaitUntilIdle();
}

using (Cm11 cm11 = new Cm11())
{
    cm11.Open("COM1");
    cm11.TurnOnDevice("A1");
    cm11.WaitUntilIdle();
}

[ToolboxBitmap(typeof(ResourceFinder), "DwellNet.Properties.16x16w.ico"),
 Description("Controls X10 devices using CM11 hardware.")]
public class Cm11 : Component, IDisposable
{
    //////////////////////////////////////////////////////////////////////////
    // Private Constants and Statics
    //

    static byte[] s_codesToNibbles = new byte[]
    {
        0x6,    // binary 0110: house code "A" or device code "1"
        0xE,    // binary 1110: house code "B" or device code "2"
        0x2,    // binary 0010: house code "C" or device code "3"
        0xA,    // binary 1010: house code "D" or device code "4"
        0x1,    // binary 0001: house code "E" or device code "5"
        0x9,    // binary 1001: house code "F" or device code "6"
        0x5,    // binary 0101: house code "G" or device code "7"
        0xD,    // binary 1101: house code "H" or device code "8"
        0x7,    // binary 0111: house code "I" or device code "9"
        0xF,    // binary 1111: house code "J" or device code "10"
        0x3,    // binary 0011: house code "K" or device code "11"
        0xB,    // binary 1011: house code "L" or device code "12"
        0x0,    // binary 0000: house code "M" or device code "13"
        0x8,    // binary 1000: house code "N" or device code "14"
        0x4,    // binary 0100: house code "O" or device code "15"
        0xC,    // binary 1100: house code "P" or device code "16"
    };

    static byte[] s_nibblesToCodes = new byte[]
    {
        12, // 0x0 binary 0000: house code "M" or device code "13"
        4,  // 0x1 binary 0001: house code "E" or device code "5"
        2,  // 0x2 binary 0010: house code "C" or device code "3"
        10, // 0x3 binary 0011: house code "K" or device code "11"
        14, // 0x4 binary 0100: house code "O" or device code "15"
        6,  // 0x5 binary 0101: house code "G" or device code "7"
        0,  // 0x6 binary 0110: house code "A" or device code "1"
        8,  // 0x7 binary 0111: house code "I" or device code "9"
        13, // 0x8 binary 1000: house code "N" or device code "14"
        5,  // 0x9 binary 1001: house code "F" or device code "6"
        3,  // 0xA binary 1010: house code "D" or device code "4"
        11, // 0xB binary 1011: house code "L" or device code "12"
        15, // 0xC binary 1100: house code "P" or device code "16"
        7,  // 0xD binary 1101: house code "H" or device code "8"
        1,  // 0xE binary 1110: house code "B" or device code "2"
        9,  // 0xF binary 1111: house code "J" or device code "10"
    };

    enum X10Function
    {

        AllOff = 0,

        AllLightsOn = 1,

        On = 2,

        Off = 3,

        Dim = 4,

        Brighten = 5,

        AllLightsOff = 6,

        ExtCode = 7,

        HailReq = 8,

        HailAck = 9,

        PresetDim1 = 10,

        PresetDim2 = 11,

        ExtDataXfer = 12,

        StatusOn = 13,

        StatusOff = 14,

        StatusReq = 15
    };

    Regex s_addressRegex = new Regex(@"^([A-P])(\d{1,2})$");

    Regex s_dimRegex = new Regex(@"^(?:([A-P])\.)?Dim(\d{0,4})$");

    Regex s_brightenRegex = new Regex(@"^(?:([A-P])\.)?Brighten(\d{0,4})$");

    Regex s_functionRegex = new Regex(@"^(?:([A-P])\.)?([A-Za-z0-9]+)$");

    Regex s_hexRegex = new Regex(@"^Hex([0-9a-fA-F]*)$");

    const int SERIAL_TIMEOUT = 5000;

    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    object m_lock = new object();

    bool m_isOpen;

    int m_workerThreadId;

    WaitHandle m_workerThreadWaitHandle;

    AutoResetEvent m_wakeWorkerThread = new AutoResetEvent(false);

    ManualResetEvent m_idleEvent = new ManualResetEvent(true);

    bool m_idle = true;

    bool m_quitting;

    string m_serialPortName;

    DnSerialPort m_serialPort;

    Queue<string> m_commandQueue = new Queue<string>(20);

    long m_commandQueueChangeCount = 0;

    AddressTracker m_addressTracker = new AddressTracker(false);

#if DEBUG
    /// <summary>
    /// Tracks time from when this object was created, for debugging purposes.
    /// </summary>
    Stopwatch m_traceStopwatch = Stopwatch.StartNew();
#endif

    ISynchronizeInvoke m_invokeEventsUsing;

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    [Browsable(false)]
    public string SerialPortName
    {
        get
        {
            return m_serialPortName;
        }
    }

    [Browsable(false)]
    public bool IsOpen
    {
        get
        {
            return m_isOpen;
        }
    }

cm11.InvokeEventsUsing = Form1;

    [Description("Runs events on the thread provided by this object.  For Windows Forms applications, set this to the form.")]
    public ISynchronizeInvoke InvokeEventsUsing
    {
        get
        {
            return m_invokeEventsUsing;
        }
        set
        {
            m_invokeEventsUsing = value;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Events
    //

    [Description("Occurs when an \"On\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11DeviceNotificationEventDelegate OnReceived;

    [Description("Occurs when an \"Off\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11DeviceNotificationEventDelegate OffReceived;

    [Description("Occurs when a \"Brighten\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11BrightenOrDimNotificationEventDelegate BrightenReceived;

    [Description("Occurs when a \"Dim\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11BrightenOrDimNotificationEventDelegate DimReceived;

    [Description("Occurs when an \"AllLightsOn\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11HouseNotificationEventDelegate AllLightsOnReceived;

    [Description("Occurs when an \"AllLightsOff\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11HouseNotificationEventDelegate AllLightsOffReceived;

    [Description("Occurs when an \"AllOff\" command is transmitted by a controller or device on the X10 network.")]
    public event Cm11HouseNotificationEventDelegate AllOffReceived;

    [Description("Occurs when a notification of an event on the X10 network is received from the CM11 hardware.")]
    public event Cm11LowLevelNotificationEventDelegate Notification;

    [Description("Occurs when the Cm11 object changes from processing commands to being idle, or vice versa.")]
    public event Cm11IdleStateChangeEventDelegate IdleStateChange;

    [Description("Occurs when communication with the CM11 hardware fails, or the hardware itself fails.")]
    public event Cm11ErrorEventDelegate Error;

    [Description("Occurs when the Cm11 object has information to provide to the application that may be useful for later review by the user.")]
    public event Cm11LogMessageEventDelegate LogMessage;

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public void Open(string serialPortName)
    {
        TraceInfo("Open");

        lock (m_lock)
        {
            // make sure we're not already open
            if (m_isOpen)
                throw new InvalidOperationException(Resources.AlreadyOpen);

            // update state
            m_serialPortName = serialPortName;

            // open the serial port, if it wasn't opened yet
            OpenSerialPort();

            // start the worker thread, if it wasn't started yet
            if (m_workerThreadWaitHandle == null)
            {
                // start the thread
                VoidDelegate workerThreadDelegate = WorkerThread;
                IAsyncResult ar = workerThreadDelegate.BeginInvoke(null, null);

                // initialize <m_workerThreadHandle>
                m_workerThreadWaitHandle = ar.AsyncWaitHandle;

                // wait until the worker thread has started to ensure that
                // <m_workerThreadId> is initialized before Open() returns;
                // note that this is the opposite of the normal usage of
                // <m_wakeWorkerThread>, since in this case the application
                // thread is using it to wait on the worker thread rather than
                // vice versa
                m_wakeWorkerThread.WaitOne();
            }

            // update state
            m_isOpen = true;
        }
    }

    public void Close()
    {
        TraceInfo("Close");

        // update state; don't rely on <isOpen> to tell us if the object is
        // open or closed, since if an exception occurred inside Open() then
        // <isOpen> will be false but some resources may still need to be
        // cleaned up
        m_isOpen = false;
        m_serialPortName = null;

        // do nothing further if we're already closed
        if (m_workerThreadWaitHandle == null)
            return;

        // tell the worker thread that it's quitting time
        m_quitting = true;
        m_wakeWorkerThread.Set();

        // Wait for the worker thread to quit -- unless we're currently
        // running in the worker thread.
        //
        // Consider the following two scenarios:
        //
        // Scenario 1:  The worker thread fires an event.  While the event is
        // executing on the worker thread, the user closes the application,
        // which causes Close() to be called on the application's UI thread.
        // No problem: Close() sets <m_quitting> to true and waits on
        // <m_workerThreadWaitHandle> and eventually the event handler returns
        // and the worker thread notices that <m_quitting> is true and quits.
        //
        // Scenario 2:  The worker thread fires event; in application's event
        // handler the application calls Close().  (Note that this time we're
        // executing Close() in the worker thread.)  Close() sets <m_quitting>
        // to true and waits on <m_workerThreadWaitHandle>.  The result is a
        // deadlock: the current thread will never exit because it's waiting
        // for itself to exit.
        //
        // Moral of the story: don't wait on <m_workerThreadWaitHandle> if the
        // current thread is the worker thread.
        //
        if (m_workerThreadId != Thread.CurrentThread.ManagedThreadId)
            m_workerThreadWaitHandle.WaitOne();
    }

cm11.Execute("A1 A2 A3 On Dim25 B1 Off");

    public void Execute(string commands)
    {
        TraceInfo("Execute: queue: {0}", commands);

        // "lock (m_lock)" is not called here because we don't want to block
        // unnecessarily -- we're just adding commands to the queue, and
        // <m_commandQueue> has its own lock

        // make sure Open() was called
        if (!m_isOpen)
            throw new InvalidOperationException(Resources.NotOpen);

        // split <commands> into an array of individual commands, one per
        // command per array element
        string[] commandArray = commands.Split(
            new char[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);

        // perform two passes: in the first pass, check the syntax of each
        // command; in the second, add the command to the command queue;
        // the purpose of this two-pass approach is to reduce the chance of
        // having invalid commands in the queue...

        // pass one:
        AddressTracker addressTracker = new AddressTracker(true);
        foreach (string command in commandArray)
            ProcessCommand(command, addressTracker, false);

        // pass two:
        foreach (string command in commandArray)
        {
            lock (m_commandQueue)
            {
                m_commandQueue.Enqueue(command);
                m_commandQueueChangeCount++;
                SetIdleState(false);
            }
        }

        // wake up the worker thread so it can process the commands
        m_wakeWorkerThread.Set();
    }

    public void Clear()
    {
        // make sure Open() was called
        if (!m_isOpen)
            throw new InvalidOperationException(Resources.NotOpen);

        // clear the command queue
        lock (m_commandQueue)
        {
            m_commandQueue.Clear();
            m_commandQueueChangeCount++;
            SetIdleState(true);
        }
    }

cm11.Open("COM1");
cm11.TurnOnDevice("A1");

    public void TurnOnDevice(string address)
    {
        // prevalidate <address>: make sure the string contains only a single
        // command; beyond that, Execute() will complete validaton of <address>
        if (address.IndexOf(' ') >= 0)
        {
            throw new Cm11InvalidCommandException(Resources.InvalidAddress,
                    address);
        }

        // execute the necessary commands
        Execute(String.Format("{0} On", address));
    }

cm11.Open("COM1");
cm11.TurnOffDevice("A1");

    public void TurnOffDevice(string address)
    {
        // prevalidate <address>: make sure the string contains only a single
        // command; beyond that, Execute() will complete validaton of <address>
        if (address.IndexOf(' ') >= 0)
        {
            throw new Cm11InvalidCommandException(Resources.InvalidAddress,
                    address);
        }

        // execute the necessary commands
        Execute(String.Format("{0} Off", address));
    }

cm11.Open("COM1");
cm11.BrightenLamp("A1", 33);

    public void BrightenLamp(string address, int percent)
    {
        // prevalidate <address>: make sure the string contains only a single
        // command; beyond that, Execute() will complete validaton of <address>
        if (address.IndexOf(' ') >= 0)
        {
            throw new Cm11InvalidCommandException(Resources.InvalidAddress,
                    address);
        }

        // execute the necessary commands
        Execute(String.Format("{0} Brighten{1}", address, percent));
    }

cm11.Open("COM1");
cm11.DimLamp("A1", 33);

    public void DimLamp(string address, int percent)
    {
        // prevalidate <address>: make sure the string contains only a single
        // command; beyond that, Execute() will complete validaton of <address>
        if (address.IndexOf(' ') >= 0)
        {
            throw new Cm11InvalidCommandException(Resources.InvalidAddress,
                    address);
        }

        // execute the necessary commands
        Execute(String.Format("{0} Dim{1}", address, percent));
    }

    public void WaitUntilIdle()
    {
        // make sure Open() was called
        if (!m_isOpen)
            throw new InvalidOperationException(Resources.NotOpen);

        // "lock (m_lock)" is not needed here
        m_idleEvent.WaitOne();
    }

    //////////////////////////////////////////////////////////////////////////
    // Event Handlers for <m_serialPort>
    //

    void m_serialPort_DataReceived(object sender, SerialDataReceivedEventArgs e)
    {
        // if we received bytes, notify the worker thread
        TraceInfo("Serial port: DataReceived ({0})", e.EventType);
        if (e.EventType == SerialData.Chars)
            m_wakeWorkerThread.Set();
    }

    void m_serialPort_ErrorReceived(object sender,
        SerialErrorReceivedEventArgs e)
    {
        // a serial port communication error occurred -- log informatin to the
        // application and resync
        FireLogMessage(Resources.SerialPortError, e.EventType);
        HardResync();
    }

    //////////////////////////////////////////////////////////////////////////
    // IDisposable Implemention
    //

    void IDisposable.Dispose()
    {
        Close();
    }

    //////////////////////////////////////////////////////////////////////////
    // Private Methods
    //
    // NOTE: These private properties and methods are generally NOT
    // thread-safe -- call these methods within "lock (m_lock)" or an
    // equivalent.
    //

    void OpenSerialPort()
    {
        // do nothing if OpenSerialPort() was already called
        if (m_serialPort != null)
            return;

        // create and initialize <m_serialPort>
        m_serialPort = new DnSerialPort(new DnSerialPortStringResources(),
            m_serialPortName, 4800, Parity.None, 8, StopBits.One);
        m_serialPort.DataReceived += new SerialDataReceivedEventHandler(
            m_serialPort_DataReceived);
        m_serialPort.ErrorReceived += new SerialErrorReceivedEventHandler(
            m_serialPort_ErrorReceived);
        m_serialPort.Open();
    }

    void CloseSerialPort()
    {
        if (m_serialPort != null)
        {
            m_serialPort.Purge();
            m_serialPort.Close();
            m_serialPort = null;
        }
    }

    void WorkerThread()
    {
        TraceInfo("worker thread started");
        // initialize <m_workerThreadId>
        m_workerThreadId = Thread.CurrentThread.ManagedThreadId;

        // allow Open() to complete, now that <m_workerThreadId> has been
        // initialized; note that this is the opposite of the normal usage of
        // <m_wakeWorkerThread>, since in this case the application thread is
        // using it to wait on the worker thread rather than vice versa
        m_wakeWorkerThread.Set();

        TraceInfo("worker thread initialized");

        // process commands in the command queue until we're told to quit;
        // NOTE: we don't "lock (m_lock)" until absolutely necessary, since
        // doing so restricts concurrent access
        try
        {
            while (true)
            {
                try
                {
                    // wait for one of the following events:
                    //   (a) serial port data the CM11;
                    //   (b) a command from the application (from Execute());
                    //   (c) Close() called -- this causes a QuittingException
                    //       to be thrown
                    WaitResult wr =
                        WaitForSerialInputOrCommand(DateTime.MaxValue, true);
                    if (wr == WaitResult.SerialInput)
                        ProcessNotification();
                    else
                    if (wr == WaitResult.CommandQueued)
                        ProcessQueuedCommands();
                }
                catch (TimeoutException ex)
                {
                    // the CM11 took too long to reply during an exchange with
                    // the PC -- pause to allow the CM11 to return to a
                    // "normal" state (waiting for a command or sending a
                    // notification)
                    TraceException(ex);
                    FireLogMessage(Resources.Cm11ReplyTimeout);
                    SoftResync();
                }
                catch (HardResyncException ex)
                {
                    // a serious serial port error occurred -- close and reopen
                    // the serial port, and discard any queued commands
                    TraceException(ex, "HardResyncException");
                    HardResync();
                }
                catch (DnSerialPortException ex)
                {
                    // a serious serial port error occurred -- close and reopen
                    // the serial port, and discard any queued commands
                    TraceException(ex);
                    FireLogMessage(Resources.CommunicationError,
                        GetExceptionFullMessage(null, ex));
                    HardResync();
                }
            }
        }
        catch (QuittingException ex)
        {
            // stop worker thread by exiting this method
            TraceException(ex);
        }

        TraceInfo("worker thread exiting");

        // clear state
        m_workerThreadId = 0;
        m_workerThreadWaitHandle = null;

        // close the serial port, if it's open
        lock (m_lock)
            CloseSerialPort();

        TraceInfo("worker thread exited");
    }

    void ProcessNotification()
    {
        // set <b1> to the first byte of the notification; return if none
        byte? b1 = m_serialPort.ReadByte();
        if (!b1.HasValue)
            return;

        // process the notification
        if (b1 == 0xA5)
        {
            // this is a *clock set request*, i.e. the CM11 is requesting that
            // we set its internal clock...

            // feedback to application
            FireLogMessage(Resources.Cm11Notification, b1,
                Resources.Cm11TimeRequestNotification);

            // set <reply> to a *clock set reply* to send to the CM11...
            DateTime now = DateTime.Now;
            int minutes = now.Hour * 60 + now.Minute;
            DateTime startOfYear = new DateTime(now.Year, 1, 1);
            int dayOfYear = (int) (now - startOfYear).TotalDays;
            byte[] reply = new byte[]
            {
                // set-time header:
                0x9B,
                // seconds component of current time
                (byte) now.Second,
                // (minute-of-day component of current time) % 120
                (byte) (minutes % 120), 
                // (minute-of-day component of current time) / 120
                (byte) (minutes / 120),
                // low order 8 bits of day of the year
                (byte) (dayOfYear & 0xFF),
                // high order bit of day of the year in MSB,
                // day of week specified by setting bit 0 (Sunday)
                // through 7 (Saturday)
                (byte) (((dayOfYear & 0x100) >> 1) |
                        (1 << (int) now.DayOfWeek)),
                // monitored house code in upper 4 bits; bit 3 is
                // reserved; bit 2 is battery timer clear flag;
                // bit 1 is monitored status clear flag; bit 0 is
                // timer purge flag
                (byte) (s_codesToNibbles[0] << 4)
            };

            // write <reply> to the CM11
            WriteToSerialPort(reply, Resources.SettingCm11Clock);

            // the CM11 will send one 0xA5 request every second after power-up,
            // so it's not unusual for a series of these to be present in the
            // serial input buffer; for efficiency, delete all remaining 0xA5
            // bytes in the input buffer
            while (m_serialPort.PeekByte() == 0xA5)
                m_serialPort.ReadByte();
        }
        else
        if (b1 == 0x5A)
        {
            // this is a *device notification*...

            // feedback to application
            FireLogMessage(Resources.Cm11Notification, b1,
                Resources.Cm11X10DeviceNotification);

            // tell the CM11 we received the first byte of the notification
            WriteToSerialPort(new byte[] { 0xC3 }, Resources.AckNotification);

            // wait for the CM11 to send a count of data bytes; ignore all
            // 0x5A bytes we receive, because those are likely just extra
            // 0x5A's that got queued before we got around to responding
            // (since the CM11 sends one 0x5A per second until we respond)
            int dataByteCount;
            while (true)
            {
                if ((dataByteCount = ReadSerialPortByte(SERIAL_TIMEOUT))
                    != 0x5A)
                    break;
            }
            FireLogMessage(Resources.Cm11NotificationDataLength, dataByteCount);
            if ((dataByteCount < 2/*note below*/) || (dataByteCount > 9))
            {
                // invalid data byte count -- ignore this notification;
                // note that there must be at least 2 data bytes: one for the
                // data byte specifier and at least one following data byte
                FireLogMessage(Resources.InvalidReply);
                SoftResync();
                return;
            }

            // read the specified number of bytes from the CM11
            byte[] dataBytes = ReadSerialPortBytes(dataByteCount,
                SERIAL_TIMEOUT);
            FireLogMessage("CM11 --> {0} ({1})", FormatBytes(dataBytes),
                Resources.DeviceNotificationData);

            // parse and process the notification bytes
            NotificationDataParser parser =
                new NotificationDataParser(dataBytes);
            while (!parser.AtEndOfDataBytes)
            {
                bool isFunctionCode;
                byte dataByte = parser.GetNextDataByte(out isFunctionCode);
                if (!isFunctionCode)
                {
                    // this is an *address code*
                    ProcessDeviceNotification(false, dataByte, 0);
                }
                else
                {
                    // this is a *function code* -- check to see if there is
                    // a following *function parameter* byte and set
                    // <parameterByte> to it if so, otherwise set
                    // <parameterByte> to zero
                    byte parameterByte = 0;
                    if (((dataByte & 0xF) == (int) X10Function.Dim) ||
                        ((dataByte & 0xF) == (int) X10Function.Brighten))
                    {
                        // this is a *function code* that requires a parameter
                        if (!parser.AtEndOfDataBytes)
                        {
                            bool isFunctionCode2;
                            byte b = parser.GetNextDataByte(
                                out isFunctionCode2);
                            if (!isFunctionCode2)
                                parameterByte = b;
                            else
                                parser.UngetDataByte();
                        }
                    }
                    ProcessDeviceNotification(true, dataByte, parameterByte);
                }
            }
        }
        else
        {
            // unknown notification (ignored)
            FireLogMessage(Resources.Cm11Notification, b1,
                Resources.Cm11UnknownNotification);
        }
    }

    void ProcessDeviceNotification(bool isFunctionCode, byte dataByte,
        byte parameterByte)
    {
        // set <commandName> to the string version of the notification,
        // e.g. "On" or "Dim"; set <commandParameter> to the parameter value,
        // i.e. a brighten-by or dim-by value in the range 0 to 100 inclusive
        // in the case of "Dim" and "Brighten" commands, -1 otherwise
        string commandName;
        int commandParameter;
        if (isFunctionCode)
        {
            // this is a *function code*
            X10Function x10Function = (X10Function) (dataByte & 0xF);
            byte highNibble = (byte) ((dataByte >> 4) & 0xF);
            if ((x10Function == X10Function.Dim) ||
                (x10Function == X10Function.Brighten))
            {
                // this is a "Dim" or "Brighten" notification
                commandName = String.Format("{0}.{1}",
                    HouseCodeNibbleToChar(highNibble), x10Function);
                commandParameter = (parameterByte * 100 + 105) / 210;

                // keep track of which devices are *currently addressed*
                m_addressTracker.RegisterFunctionCommand(highNibble);
            }
            else
            if ((x10Function == X10Function.PresetDim1) ||
                (x10Function == X10Function.PresetDim2))
            {
                // this is a *device level notification* -- see Cm11.doc
                byte appended5Bits = (byte) ((highNibble << 1) |
                    ((x10Function == X10Function.PresetDim2) ? 1 : 0));
                byte reversed5Bits = (byte)
                    (((appended5Bits & 0x10) >> 4) |
                     ((appended5Bits & 0x08) >> 2) |
                     (appended5Bits & 0x04) |
                     ((appended5Bits & 0x02) << 2) |
                     ((appended5Bits & 0x01) << 4));
                commandName = "Level";
                commandParameter = ((reversed5Bits + 1) * 100 + 16) / 32;
            }
            else
            {
                // this is some other *function code* notification
                commandName = String.Format("{0}.{1}",
                    HouseCodeNibbleToChar(highNibble), x10Function);
                commandParameter = -1;

                // keep track of which devices are *currently addressed*
                m_addressTracker.RegisterFunctionCommand(highNibble);
            }
        }
        else
        {
            // this is an *address code* notification
            commandName = AddressByteToString(dataByte);
            commandParameter = -1;

            // keep track of which devices are *currently addressed*
            m_addressTracker.RegisterAddressCommand(dataByte);
        }

        // fire a low-level notification event
        FireNotification(commandName, commandParameter);

        // fire a high-level notification event, if appropriate
        int percent;
        if (isFunctionCode)
        {
            X10Function x10Function = (X10Function) (dataByte & 0xF);
            byte houseCodeNibble = (byte) ((dataByte >> 4) & 0xF);
            switch (x10Function)
            {

            case X10Function.On:

                foreach (string address in
                        m_addressTracker.GetAddressedDevices(houseCodeNibble))
                    FireOnReceived(address);
                break;

            case X10Function.Off:

                foreach (string address in
                        m_addressTracker.GetAddressedDevices(houseCodeNibble))
                    FireOffReceived(address);
                break;

            case X10Function.Brighten:

                percent = (parameterByte * 100 + 105) / 210;
                foreach (string address in
                        m_addressTracker.GetAddressedDevices(houseCodeNibble))
                    FireBrightenReceived(address, percent);
                break;

            case X10Function.Dim:

                percent = (parameterByte * 100 + 105) / 210;
                foreach (string address in
                        m_addressTracker.GetAddressedDevices(houseCodeNibble))
                    FireDimReceived(address, percent);
                break;

            case X10Function.AllLightsOn:

                FireAllLightsOnReceived(
                    HouseCodeNibbleToChar(houseCodeNibble));
                break;

            case X10Function.AllLightsOff:

                FireAllLightsOffReceived(
                    HouseCodeNibbleToChar(houseCodeNibble));
                break;

            case X10Function.AllOff:

                FireAllOffReceived(HouseCodeNibbleToChar(houseCodeNibble));
                break;
            }
        }
    }

    void ProcessQueuedCommands()
    {
        // process
        while (true)
        {
            // return if Close() was called or serial input is received from
            // the CM11; in the latter case is due to the fact that we need to
            // process C11 notifications before executing commands, because the
            // CM11 ignores commands while it's in notification mode
            WaitResult wr = WaitForSerialInputOrCommand(null, true);
            if (wr != WaitResult.CommandQueued)
                return;

            // set <command> to the next command in the queue, but don't remove
            // it from the queue yet
            string command;
            lock (m_commandQueue)
            {
                // check the command queue again in case it was emptied by
                // another thread
                if (m_commandQueue.Count == 0)
                    return;
                command = m_commandQueue.Peek();
            }

            // execute <command> -- don't "lock <m_commandQueue>" here because
            // ProcessCommand() could take quite a while and we don't want to
            // lock the command queue for the entire time
            if (ProcessCommand(command, m_addressTracker, true))
            {
                // the command was successfully executed -- remove it from the
                // queue
                lock (m_commandQueue)
                {
                    // check the command queue again in case it was emptied by
                    // another thread (with possibly another command queued --
                    // we don't want to delete the wrong command)
                    if ((m_commandQueue.Count > 0) &&
                        (command == m_commandQueue.Peek()))
                    {
                        m_commandQueue.Dequeue();
                        m_commandQueueChangeCount++;
                    }
                    if (m_commandQueue.Count == 0)
                        SetIdleState(true);
                }
            }
            else
            {
                // the command could not be executed, presumably because a
                // notification arrived from the CM11 -- leave the command in
                // the queue for now, and return so the notification can be
                // processed
                return;
            }
        }
    }

    void SoftResync()
    {
        try
        {
            FireLogMessage(Resources.Pausing, SERIAL_TIMEOUT);
            Wait(SERIAL_TIMEOUT);
        }
        catch (HardResyncException ex)
        {
            // a serious serial port error occurred -- close and reopen
            // the serial port, and discard any queued commands
            TraceException(ex, "HardResyncException during SoftResync");
            HardResync();
        }
        catch (DnSerialPortException ex)
        {
            // a serious serial port error occurred -- close and reopen
            // the serial port, and discard any queued commands
            TraceException(ex, "DnSerialPortException during SoftResync");
            HardResync();
        }
    }

    void HardResync()
    {
        // loop until the serial port is successfully reopened
        for (int attemptNumber = 1; ; attemptNumber++)
        {
            TraceInfo("HardResync: attempt #{0}", attemptNumber);
            try
            {
                // purge the serial port input and output buffers, then close
                // the serial port
                CloseSerialPort();

                // discard any queued commands; set <discardedMessageCount> to
                // the number of discarded messages
                int discardedMessagesCount;
                lock (m_commandQueue)
                {
                    discardedMessagesCount = m_commandQueue.Count;
                    Clear();
                }

                // notify the application of the situation
                FireError(Resources.HardResyncOccurred,
                        discardedMessagesCount);

                // give the CM11 time to reset its state; this also prevents
                // rapid close/open/close/open/etc. of the serial port if
                // reopening the serial port (below) fails continually
                Wait(SERIAL_TIMEOUT);

                // reopen the serial port and purge any collected serial port
                // input
                OpenSerialPort();
                m_serialPort.Purge();

                // done with no exceptions
                FireLogMessage(Resources.HardResyncComplete);
                break;
            }
            catch (HardResyncException ex)
            {
                TraceException(ex,
                    "HardResyncException during HardResync");
            }
            catch (DnSerialPortException ex)
            {
                TraceException(ex, "DnSerialPortException during HardResync");
            }
        }
    }

    void Wait(int timeoutMsec)
    {
        DateTime timeoutTime = DateTime.Now.AddMilliseconds(timeoutMsec);
        bool timeout = false;
        while (true)
        {
            // if Close() was called, it's time to quit
            if (m_quitting)
                throw new QuittingException();

            // see if it's time to return
            if (timeout)
                return;

            // sleep until m_wakeWorkerThread.Set() is called or we reach
            // <timeoutTime> (if not null), whichever happens first; set
            // <timeout> to true if the latter happens first, false if the
            // former happens first
            TimeSpan sleepTime = timeoutTime - DateTime.Now;
            if (sleepTime <= TimeSpan.Zero)
                timeout = true;
            else
                timeout = !m_wakeWorkerThread.WaitOne(sleepTime, false);
        }
    }

    WaitResult WaitForSerialInputOrCommand(DateTime? timeoutTime,
        bool waitForCommand)
    {
        bool timeout = false; // true once a timeout occurs
        while (true)
        {
            // if Close() was called, it's time to quit
            if (m_quitting)
                throw new QuittingException();

            // check to see if one or more bytes are now present at the serial
            // port
            if (m_serialPort.PeekByte() != null)
                return WaitResult.SerialInput;

            // check to see if a command is already available in the queue,
            // unless <waitForCommand> is false
            if (waitForCommand)
            {
                lock (m_commandQueue)
                {
                    if (m_commandQueue.Count > 0)
                        return WaitResult.CommandQueued;
                }
            }

            // if the caller is polling, return immediately
            if (timeoutTime == null)
                return WaitResult.Idle;

            // if a timeout occurred in a previous iteration of this loop,
            // throw TimeoutException
            if (timeout)
            {
                TraceInfo("WaitForSerialInputOrCommand: Timeout: {0} msec late",
                    (DateTime.Now - timeoutTime.Value).TotalMilliseconds);
                throw new TimeoutException();
            }

            // sleep until m_wakeWorkerThread.Set() is called or we reach
            // <timeoutTime>, whichever happens first; set <timeout> to true
            // if the latter happens first, false if the former happens first
            if (timeoutTime.Value != DateTime.MaxValue)
            {
                // wait for the specified time
                TimeSpan sleepTime = timeoutTime.Value - DateTime.Now;
                if (sleepTime <= TimeSpan.Zero)
                    timeout = true;
                else
                    timeout = !m_wakeWorkerThread.WaitOne(sleepTime, false);
            }
            else
            {
                // wait indefinitely
                m_wakeWorkerThread.WaitOne();
            }
        }
    }

    void WaitForSerialInput(DateTime timeoutTime)
    {
        WaitResult wr = WaitForSerialInputOrCommand(timeoutTime, false);
        Debug.Assert(wr == WaitResult.SerialInput);
    }

    void SetIdleState(bool idle)
    {
        // do nothing if the idle state hasn't changed
        if (m_idle == idle)
            return;
        m_idle = idle;

        // update <m_idleEvent> (used by WaitUntilIdle)
        if (m_idle)
            m_idleEvent.Set();
        else
            m_idleEvent.Reset();

        // notify the application of the idle state change
        FireIdleStateChange(m_idle);
    }

    byte ReadSerialPortByte(int timeoutMsec)
    {
        DateTime timeoutTime = DateTime.Now.AddMilliseconds(timeoutMsec);
        while (true)
        {
            WaitForSerialInput(timeoutTime);
            byte? b = m_serialPort.ReadByte();
            if (b.HasValue)
                return b.Value;
        }
    }

    byte PeekSerialPortByte(int timeoutMsec)
    {
        DateTime timeoutTime = DateTime.Now.AddMilliseconds(timeoutMsec);
        while (true)
        {
            WaitForSerialInput(timeoutTime);
            byte? b = m_serialPort.PeekByte();
            if (b.HasValue)
                return b.Value;
        }
    }

    byte[] ReadSerialPortBytes(int byteCount, int timeoutMsec)
    {
        DateTime timeoutTime = DateTime.Now.AddMilliseconds(timeoutMsec);
        byte[] result = new byte[byteCount];
        int offset = 0; // where in <result> to read next
        while (true)
        {
            int bytesDesired = byteCount - offset;
            if (bytesDesired <= 0)
                return result;
            WaitForSerialInput(timeoutTime);
            int bytesRead = m_serialPort.Read(result, offset, bytesDesired);
            offset += bytesRead;
        }
    }

    void ExpectingEmptySerialInputBuffer()
    {
        // read all bytes in the serial input buffer; set <bytesList> to
        // a string containing the bytes in hex format (e.g. "8A B2 1C")
        StringBuilder bytesList = null;
        while (m_serialPort.PeekByte() != null)
        {
            if (bytesList == null)
                bytesList = new StringBuilder(100);
            else
                bytesList.Append(' ');
            bytesList.AppendFormat("{0:X2}", m_serialPort.ReadByte());
        }

        // if any bytes were read, throw an exception
        if (bytesList != null)
        {
            FireLogMessage(Resources.Cm11UnexpectedBytes, bytesList);
        }
    }

    bool ProcessCommand(string command, AddressTracker addressTracker,
        bool execute)
    {
        // parse <command>; set <commandBytes> to the byte sequence for the
        // X10 address or function corresponding to <command>; set
        // <commandLabel> to a label for the command to use in a LogMessage
        // event; exception: if <command> is just a house code ("A" through
        // "P", inclusive), just set <m_currentHouseCodeNibble> and return,
        // since this command simply sets internal state in this class -- no
        // communication with the CM11 hardware is required
        byte[] commandBytes;
        string commandLabel;
        byte? houseCodeNibble;
        byte? addressByte;
        bool hexCommand;
        if ((addressByte = ParseAddress(command)) != null)
        {
            // <command> is an X10 address, e.g. "A1"...

            // this isn't a "Hex<hex-digits>" command
            hexCommand = false;

            // set <commandLabel> to a string to use in the LogMessage event
            commandLabel = String.Format(Resources.CommandType, command);

            // set <houseCodeNibble> to the nibble value of the house
            // code of this address
            houseCodeNibble = (byte) (addressByte.Value >> 4);

            // set <commandBytes> to the byte sequence for an X10 address
            commandBytes = new byte[] { (byte) 0x04, addressByte.Value };

            // update the state of <addressTracker>
            addressTracker.RegisterAddressCommand(addressByte.Value);
        }
        else
        if ((commandBytes = ParseHexCommand(command)) != null)
        {
            // <command> is a "Hex<hex-digits>" command
            hexCommand = true;

            // set <commandLabel> to a string to use in the LogMessage event
            commandLabel = String.Format(Resources.CommandType, command);
        }
        else
        if ((commandBytes = ParseFunction(command,
                addressTracker.LastCommandHouseCodeNibble)) != null)
        {
            // <command> is an X10 function, e.g. "Dim70"...

            // this isn't a "Hex<hex-digits>" command
            hexCommand = false;

            // set <commandLabel> to a string to use in the LogMessage event
            houseCodeNibble = (byte) ((commandBytes[1] >> 4) & 0xF);
            X10Function x10Function = (X10Function) (commandBytes[1] & 0xF);
            int amount22 = (commandBytes[0] >> 3) & 0x1F;
            commandLabel = String.Format(Resources.CommandType,
                FormatFunctionCommand(houseCodeNibble.Value, x10Function,
                    amount22));

            // update the state of <addressTracker>
            addressTracker.RegisterFunctionCommand(houseCodeNibble.Value);
        }
        else
        {
            // <command> is invalid
            throw new Cm11InvalidCommandException(Resources.InvalidCommand,
                command);
        }

        // if we're only performing a syntax & usage check, we're done
        if (!execute)
            return false; // command not executed

        // send the command to the CM11, and wait for a correct checksum reply;
        // retry sending the command a few times if necessary
        for (int retry = 0; ; retry++)
        {
            // if we ran out of retries, reset communications
            int maxRetries = 5;
            if (retry > maxRetries)
            {
                FireLogMessage(Resources.CommandRetryCountExceeded, maxRetries);
                throw new HardResyncException();
            }

            // if this is a retry, tell the application
            if (retry > 0)
                FireLogMessage(Resources.RetryingCommand);

            // just before writing to the serial port we need to check to see
            // if the serial input buffer is empty; if it's not, we should
            // abort sending this command to the CM11 because the CM11 will
            // ignore any command sent while it is in *device notification
            // mode*
            if (m_serialPort.PeekByte() != null)
                return false; // command not executed

            // send a *normal command* or a raw hex command to the CM11 device
            WriteToSerialPort(commandBytes, "{0}", commandLabel);

            // if we sent a raw hex command, we're done -- for example we can't
            // assume that a checksum is to be expected
            if (hexCommand)
                return true;

            // wait for a checksum from the CM11
            byte receivedChecksum;
            try
            {
                receivedChecksum = PeekSerialPortByte(SERIAL_TIMEOUT);
            }
            catch (TimeoutException ex)
            {
                // timeout -- try again
                TraceException(ex);
                continue;
            }
            FireLogMessage(Resources.Cm11Checksum, receivedChecksum);

            // if the checksum is correct move on to the next step of the
            // protocol
            byte correctChecksum = CalculateChecksum(commandBytes);
            if (receivedChecksum == correctChecksum)
            {
                // we "peeked" the checksum above, so read it now
                ReadSerialPortByte(SERIAL_TIMEOUT);
                break;
            }

            // incorrect checksum
            FireLogMessage(Resources.IncorrectChecksum, correctChecksum);
            if (receivedChecksum == 0x5A)
            {
                // Our command probably** got interrupted by a notification;
                // leave the 0x5A in the serial input buffer and return so
                // the notification can be processed before the command is
                // retried (since the CM11 ignores commands while it's in
                // *device notification mode*.
                //
                // ** Why "probably"? because it's possible that 0x5A is simply
                // the wrong checksum.  (It's also possible that the correct
                // checksum is 0x5A and we incorrectly assumed success above.)
                // If that happens, we'll let the normal resync logic of Cm11
                // take care of the (hopefully rare) situation.
                //
                FireLogMessage(Resources.PushedByteBack, receivedChecksum);
                return false;
            }
            else
            {
                // plain old wrong checksum -- read it (we "peeked" it above),
                // wait for a short period (in case the CM11 is in the middle
                // of sending a bunch of other bytes), then purge the remaining
                // serial port input and output buffer contents and try again
                ReadSerialPortByte(SERIAL_TIMEOUT);
                Wait(250);
                m_serialPort.Purge();
            }
        }

        // the CM11 sent a correct checksum; acknowledge it with a 0x00
        ExpectingEmptySerialInputBuffer();
        WriteToSerialPort(new byte[] { 0x00 }, Resources.AckChecksum);

        // wait for a 0x55 or 0x5A reply from the CM11
        byte ackReply = PeekSerialPortByte(SERIAL_TIMEOUT);
        FireLogMessage(Resources.Cm11AckReply, ackReply);
        if (ackReply == 0x55)
        {
            // the command was successfully executed -- we "peeked" <ackReply>
            // above above, so read it now
            ReadSerialPortByte(SERIAL_TIMEOUT);
            return true;
        }
        else
        if (ackReply == 0x5A)
        {
            // the command was successfully executed; during the command,
            // the CM11 received a powerline notification which it is now
            // sending to the PC -- leave the 0x5A in the serial port "peek"
            // buffer so the notification will be processed next
            FireLogMessage(Resources.PushedByteBack, ackReply);
            return true;
        }
        else
        {
            // reply incorrect -- reset communications; we "peeked" <ackReply>
            // above above, so read it now
            ReadSerialPortByte(SERIAL_TIMEOUT);
            FireLogMessage(Resources.IncorrectChecksumAckReply);
            throw new HardResyncException();
        }
    }

    byte? ParseHouseCode(string houseCode)
    {
        if (houseCode.Length != 1)
            return null;
        return HouseCodeToNibble(houseCode[0], false);
    }

    byte? ParseAddress(string address)
    {
        // parse <address>; set <houseCodeNibble> and <deviceCodeNibble> to
        // the corresponding house code and device code nibbles; throw a
        // Cm11InvalidCommandException if the device code is out of range
        Match match = s_addressRegex.Match(address);
        if (!match.Success)
            return null;
        byte houseCodeNibble = HouseCodeToNibble(
            match.Groups[1].Value[0], true).Value;
        byte deviceCodeNibble = DeviceCodeToNibble(
            int.Parse(match.Groups[2].Value));

        // return the byte code corresponding to this address
        return (byte) ((houseCodeNibble << 4) | deviceCodeNibble);
    }

    static string AddressByteToString(byte addressCode)
    {
        return HouseCodeNibbleToChar((byte) ((addressCode >> 4) & 0xF)) +
            DeviceCodeNibbleToString((byte) (addressCode & 0xF));
    }

    byte[] ParseFunction(string command, int defaultHouseCodeNibble)
    {
        // see if <command> is a "Dim<percent>" command; if so, return its
        // 2-byte sequence
        byte[] bytes = ParseBrightenOrDimCommand(command,
            defaultHouseCodeNibble);
        if (bytes != null)
            return bytes;

        // see if <command> is follows the general syntax of any other
        // *function command* (than the ones checked for above); if so, set
        // <houseCode> and <commandName> to its house code prefix (e.g. "A", or
        // "" if none) and command name (e.g. "AllLightsOn")
        Match match = s_functionRegex.Match(command);
        if (!match.Success)
            return null;
        string houseCode = match.Groups[1].Value;
        string commandName = match.Groups[2].Value;

        // see if <commandName> is an X10Function member; if so, set
        // <x10Function> to it; if not, return null since at that point we know
        // <command> is not a valid DwellNet.Cm11 command
        X10Function x10Function;
        try
        {
            x10Function = (X10Function) Enum.Parse(typeof(X10Function),
                commandName, false);
        }
        catch (ArgumentException)
        {
            return null;
        }

        // set <houseCodeNibble> to the *house code nibble* of the command,
        // using <defaultHouseCodeNibble> as a default (if provided)
        byte? houseCodeNibble = ParseHouseCode(houseCode);
        if (houseCodeNibble == null)
        {
            if (defaultHouseCodeNibble < 0)
            {
                throw new Cm11InvalidCommandException(Resources.NoHouseCode,
                    command);
            }
            else
                houseCodeNibble = (byte) defaultHouseCodeNibble;
        }

        // return the 2-byte sequence for this command
        return new byte[]
        {
            (byte) 0x06,
            (byte) ((byte) x10Function | (houseCodeNibble << 4))
        };
    }

    byte[] ParseBrightenOrDimCommand(string command,
        int defaultHouseCodeNibble)
    {
        // parse <command>; set <houseCodeNibble> to the *house code nibble*
        // (using <defaultHouseCodeNibble> as the default, if provided); set
        // <x10Function> to the X10Function value (X10Function.Dim or
        // X10Function.Brighten); set <amount> to the brighten-by or dim-by
        // percentage amount (0 to 100)
        X10Function x10Function;
        Match match = s_dimRegex.Match(command);
        if (match.Success)
            x10Function = X10Function.Dim;
        else
        {
            match = s_brightenRegex.Match(command);
            if (match.Success)
                x10Function = X10Function.Brighten;
            else
                return null; // not a "Dim" or "Brighten" command
        }
        byte? houseCodeNibble = ParseHouseCode(match.Groups[1].Value);
        if (houseCodeNibble == null)
        {
            if (defaultHouseCodeNibble < 0)
            {
                throw new Cm11InvalidCommandException(Resources.NoHouseCode,
                    command);
            }
            else
                houseCodeNibble = (byte) defaultHouseCodeNibble;
        }
        string amountString = match.Groups[2].Value;
        if (amountString.Length == 0)
        {
            // missing dim amount percent
            throw new Cm11InvalidCommandException(Resources.InvalidCommand,
                command);
        }
        int amount = int.Parse(match.Groups[2].Value);
        if (amount > 100)
        {
            throw new Cm11InvalidCommandException(Resources.BrightenOrDimAmountOutOfRange,
                amount);
        }

        // return the 2-byte sequence for this command
        return new byte[]
        {
            (byte) ((((amount * 22 + 50) / 100) << 3) | 0x06),
            (byte) ((byte) x10Function | (houseCodeNibble << 4))
        };
    }

    byte[] ParseHexCommand(string command)
    {
        // parse <command>; set <hexDigits> to the string of hexadecimal digits
        Match match = s_hexRegex.Match(command);
        if (!match.Success)
            return null; // not a "Hex<hex-digits>" command
        string hexDigits = match.Groups[1].Value;
        if ((hexDigits.Length == 0) || ((hexDigits.Length & 1) == 1))
        {
            // missing or odd number of hex-digits
            throw new Cm11InvalidCommandException(Resources.InvalidHexDigits,
                command);
        }

        // parse <hexDigits> into <bytes>
        byte[] bytes = new byte[hexDigits.Length / 2];
        for (int iByte = 0; iByte < bytes.Length; iByte++)
        {
            bytes[iByte] = (byte) int.Parse(hexDigits.Substring(iByte * 2, 2),
                System.Globalization.NumberStyles.AllowHexSpecifier);
        }

        return bytes;
    }

    string FormatFunctionCommand(byte houseCodeNibble, X10Function x10Function,
        int amount22)
    {
        if ((x10Function == X10Function.Dim) ||
            (x10Function == X10Function.Brighten))
        {
            return String.Format("{0}.{1}{2}",
                HouseCodeNibbleToChar(houseCodeNibble), x10Function,
                (amount22 * 100 + 11) / 22);
        }
        else
        {
            return String.Format("{0}.{1}",
                HouseCodeNibbleToChar(houseCodeNibble), x10Function);
        }
    }

    void WriteToSerialPort(byte[] bytes, string logMessageFormat,
        params object[] logMessageArgs)
    {
        FireLogMessage("CM11 <-- {0} ({1})", FormatBytes(bytes),
            String.Format(logMessageFormat, logMessageArgs));
        m_serialPort.Write(bytes, 0, bytes.Length);
    }

    void FireOnReceived(string address)
    {
        if (OnReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                OnReceived(address);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(OnReceived,
                    new object[] { address });
            }
        }
    }

    void FireOffReceived(string address)
    {
        if (OffReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                OffReceived(address);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(OffReceived,
                    new object[] { address });
            }
        }
    }

    void FireBrightenReceived(string address, int percent)
    {
        if (BrightenReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                BrightenReceived(address, percent);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(BrightenReceived,
                    new object[] { address, percent });
            }
        }
    }

    void FireDimReceived(string address, int percent)
    {
        if (DimReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                DimReceived(address, percent);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(DimReceived,
                    new object[] { address, percent });
            }
        }
    }

    void FireAllLightsOnReceived(char houseCode)
    {
        if (AllLightsOnReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                AllLightsOnReceived(houseCode);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(AllLightsOnReceived,
                    new object[] { houseCode });
            }
        }
    }

    void FireAllLightsOffReceived(char houseCode)
    {
        if (AllLightsOffReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                AllLightsOffReceived(houseCode);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(AllLightsOffReceived,
                    new object[] { houseCode });
            }
        }
    }

    void FireAllOffReceived(char houseCode)
    {
        if (AllOffReceived != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                AllOffReceived(houseCode);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(AllOffReceived,
                    new object[] { houseCode });
            }
        }
    }

    void FireNotification(string commandName, int commandParameter)
    {
        if (Notification != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                Notification(commandName, commandParameter);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(Notification,
                    new object[] { commandName, commandParameter });
            }
        }
    }

    void FireIdleStateChange(bool idle)
    {
        if (IdleStateChange != null)
        {
            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                IdleStateChange(idle);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(IdleStateChange,
                    new object[] { idle });
            }
        }
    }

    void FireError(string format, params object[] args)
    {
        string message = String.Format(format, args);
        TraceInfo("ERROR: " + message);
        if (Error != null)
        {

            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                Error(message);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(Error, new object[] { message });
            }
        }
    }

    void FireLogMessage(string format, params object[] args)
    {
        string message = String.Format(format, args);
        TraceInfo(message);
        if (LogMessage != null)
        {

            if ((m_invokeEventsUsing == null) ||
                !m_invokeEventsUsing.InvokeRequired)
            {
                // fire the event on the current thread
                LogMessage(message);
            }
            else
            {
                // fire the event on an application thread
                m_invokeEventsUsing.Invoke(LogMessage,
                    new object[] { message });
            }
        }
    }

    byte? HouseCodeToNibble(char houseCode, bool exceptionOnError)
    {
        if ((houseCode >= 'A') && (houseCode <= 'P'))
            return s_codesToNibbles[houseCode - 'A'];
        else
        if ((houseCode > ' ') && (houseCode < 0x7F))
        {
            if (exceptionOnError)
            {
                throw new Cm11InvalidCommandException(Resources.InvalidHouseCode,
                    houseCode);
            }
            else
                return null;
        }
        else
        {
            if (exceptionOnError)
            {
                throw new Cm11InvalidCommandException(Resources.InvalidHouseCode,
                    String.Format("0x{0:X2}", houseCode));
            }
            else
                return null;
        }
    }

    static char HouseCodeNibbleToChar(byte houseCodeNibble)
    {
        return (char) ('A' + s_nibblesToCodes[houseCodeNibble]);
    }

    byte DeviceCodeToNibble(int deviceCode)
    {
        if ((deviceCode >= 1) && (deviceCode <= 16))
            return s_codesToNibbles[deviceCode - 1];
        else
        {
            throw new Cm11InvalidCommandException(Resources.InvalidDeviceCode,
                deviceCode);
        }
    }

    static int DeviceCodeNibbleToInt(byte deviceCodeNibble)
    {
        return s_nibblesToCodes[deviceCodeNibble] + 1;
    }

    static string DeviceCodeNibbleToString(byte deviceCodeNibble)
    {
        return String.Format("{0}", DeviceCodeNibbleToInt(deviceCodeNibble));
    }

    [Conditional("DEBUG")]
    protected void TraceInfo(string format, params object[] args)
    {
#if DEBUG
        // no "lock (m_lock)" -- this operation is thread-safe
        Trace.WriteLine(String.Format("Cm11 {0:n3}: {1}",
            ((double)m_traceStopwatch.ElapsedMilliseconds) / 1000,
            String.Format(format, args)));
#endif
    }

    protected void TraceException(Exception ex)
    {
        TraceException(ex, ex.GetType().Name);
    }

    protected void TraceException(Exception ex, string format,
        params object[] args)
    {
        // no "lock (m_lock)" -- this operation is thread-safe...
        Trace.WriteLine(String.Format("Cm11: {0}{1}",
            String.Format(format, args), GetExceptionFullMessage(": ", ex)));
    }

    static string GetExceptionFullMessage(string prefix, Exception ex)
    {
        StringBuilder exceptionMessage = new StringBuilder(1000);
        while (ex != null)
        {
            if (exceptionMessage.Length == 0)
            {
                if (prefix != null)
                    exceptionMessage.Append(prefix);
            }
            else
                exceptionMessage.Append(": ");
            exceptionMessage.Append(ex.Message);
            ex = ex.InnerException;
        }
        return exceptionMessage.ToString();
    }

    static string FormatBytes(byte[] bytes)
    {
        StringBuilder result = new StringBuilder(3 * bytes.Length);
        foreach (byte b in bytes)
        {
            if (result.Length > 0)
                result.Append(' ');
            result.AppendFormat("{0:X2}", b);
        }
        return result.ToString();
    }

    static byte CalculateChecksum(byte[] bytes)
    {
        int checksum = 0;
        foreach (byte b in bytes)
            checksum += b;
        return (byte) (checksum & 0xFF);
    }

    //////////////////////////////////////////////////////////////////////////
    // Private Helper Classes and Enumerations
    //

    delegate void VoidDelegate();

    class HardResyncException : Exception
    {
    }

    class QuittingException : Exception
    {
    }

    enum WaitResult
    {

        Idle,

        SerialInput,

        CommandQueued,
    }

    class NotificationDataParser
    {
        // private fields
        byte[] m_dataBytes;
        int m_iDataByte; // index within <m_dataBytes>
        int m_dataByteSpecifier; // see Cm11.doc

        public bool AtEndOfDataBytes
        {
            get
            {
                return m_iDataByte >= m_dataBytes.Length - 1;
            }
        }

        public NotificationDataParser(byte[] dataBytes)
        {
            // initialize state 
            m_dataBytes = dataBytes;
            m_dataByteSpecifier = dataBytes[0];

            // there must be at least 2 data bytes: one for the data byte
            // specifier and at least one following data byte
            if ((dataBytes.Length < 2) || (dataBytes.Length > 9))
                throw new ArgumentException("dataBytes");

            // set <m_dataByteSpecifier> to the *data byte specifier* which
            // contains one bit for each following data byte indicating if
            // that data byte is a function code (bit = 1) or an address or
            // parameter (bit = 0) -- see Cm11.doc for more
            // information
            m_dataByteSpecifier = dataBytes[0];
        }

        public byte GetNextDataByte(out bool isFunctionCode)
        {
            // advance <m_iDataByte>, unless we're at the end of the data bytes
            if (m_iDataByte >= m_dataBytes.Length - 1)
                throw new InvalidOperationException();
            else
                m_iDataByte++;

            // set <isFunctionCode> based on the bit in <m_dataByteSpecifier>
            // corrsponding to the current index within <m_dataBytes>
            isFunctionCode =
                ((m_dataByteSpecifier >> (m_iDataByte - 1) & 1) == 1);

            // return the data byte
            return m_dataBytes[m_iDataByte];
        }

        public void UngetDataByte()
        {
            m_iDataByte--;
        }
    }

    class AddressTracker
    {

        UInt16[] m_addressedDevices = new UInt16[16];

        bool m_singleHouseMode;

        bool[] m_lastCommandWasFunction = new bool[16];

        int m_lastCommandHouseCodeNibble = -1;

        public int LastCommandHouseCodeNibble
        {
            get
            {
                return m_lastCommandHouseCodeNibble;
            }
        }

        public IEnumerable<string> GetAddressedDevices(byte houseCodeNibble)
        {
            if (houseCodeNibble >= 16)
                throw new ArgumentException("houseCodeNibble");
            UInt16 devices = m_addressedDevices[houseCodeNibble];
            char houseCode = HouseCodeNibbleToChar(houseCodeNibble);
            UInt16 mask = 1;
            byte deviceCodeNibble = 0;
            while (devices != 0)
            {
                if ((devices & mask) != 0)
                {
                    yield return String.Format("{0}{1}", houseCode,
                        DeviceCodeNibbleToInt(deviceCodeNibble));
                }
                deviceCodeNibble++;
                devices = (UInt16) (devices & ~mask);
                mask = (UInt16) (mask << 1);
            }
        }

        public AddressTracker(bool singleHouseMode)
        {
            m_singleHouseMode = singleHouseMode;
        }

        public void RegisterAddressCommand(byte addressCode)
        {
            // divide <addressCode> into nibbles
            byte houseCodeNibble = (byte) ((addressCode >> 4) & 0xF);
            byte deviceCodeNibble = (byte) (addressCode & 0xF);

            // if we're in single-house mode, it's an error for two consecutive
            // *address commands* to have different house codes
            if (m_singleHouseMode)
            {
                if ((m_lastCommandHouseCodeNibble != -1) &&
                    !m_lastCommandWasFunction[m_lastCommandHouseCodeNibble] &&
                    (m_lastCommandHouseCodeNibble != houseCodeNibble))
                {
                    throw new Cm11InvalidCommandException(
                        Resources.InconsistentHouseCodes);
                }
            }

            // update <m_addressedDevices> based on the nibbles
            if (m_lastCommandWasFunction[houseCodeNibble])
            {
                // this is the first *address command* in a sequence of one or
                // more *address commands* for this house code -- so reset all
                // device codes for this house code, except this device code,
                // to *currently not addressed* state
                m_addressedDevices[houseCodeNibble] =
                    (ushort) (1 << deviceCodeNibble);
            }
            else
            {
                // this is the second or later *address command* for this house
                // code -- add it to the set of *currently addressed* state
                m_addressedDevices[houseCodeNibble] |=
                    (ushort) (1 << deviceCodeNibble);
            }

            // update other state
            m_lastCommandWasFunction[houseCodeNibble] = false;
            m_lastCommandHouseCodeNibble = houseCodeNibble;
        }

        public void RegisterFunctionCommand(byte houseCodeNibble)
        {
            // update state
            Debug.Assert(houseCodeNibble <= 0xF);
            m_lastCommandWasFunction[houseCodeNibble] = true;
            m_lastCommandHouseCodeNibble = houseCodeNibble;
        }
    }

    internal class DnSerialPortStringResources : DnSerialPortStrings
    {
        public override string SerialPortError
        {
            get
            {
                return Resources.DnSerialPort_SerialPortError;
            }
        }
    }
}

public class Cm11InvalidCommandException : Exception
{

    internal Cm11InvalidCommandException(string format, params object[] args) :
        base(String.Format(format, args))
    {
    }
}

public class Cm11CommunicationException : Exception
{

    internal Cm11CommunicationException(string format, params object[] args) :
        base(String.Format(format, args))
    {
    }
}

public delegate void Cm11DeviceNotificationEventDelegate(string address);

public delegate void Cm11BrightenOrDimNotificationEventDelegate(string address,
    int percent);

public delegate void Cm11HouseNotificationEventDelegate(char houseCode);

public delegate void Cm11LowLevelNotificationEventDelegate(string commandName,
    int commandParameter);

public delegate void Cm11IdleStateChangeEventDelegate(bool idle);

public delegate void Cm11ErrorEventDelegate(string message);

public delegate void Cm11LogMessageEventDelegate(string message);

}

abstract internal class ResourceFinder // must not be in any namespace
{
}