/*       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);
        }
    }