tool/cafex/SerialCommunication.cs

using System;
using System.Linq;
using System.Collections.Generic;
using System.IO.Ports;
using System.Threading;
using Nintendo.SDSG;

namespace CafeX
{
    /// <summary>
    /// Provides a set of operations for interacting with the serial port, supporting CAT-R communication.
    /// </summary>
    public interface ISerialDevice : ISerialStartable, ISerialRunnable
    {
        /// <summary>
        /// Gets or sets whether to display the serial output.
        /// </summary>
        bool DisplayOutput { get; set; }
    }

    /// <summary>
    /// Provides a set of operations that are available after the serial device has successfully started.
    /// </summary>
    public interface ISerialRunnable
    {
        /// <summary>
        /// Waits for a message to come through the serial stream.  This will use the default timeout (1 min).
        /// </summary>
        /// <param name="message">Message to look for.</param>
        ISerialRunnable WaitForMessage(string message);

        /// <summary>
        /// Waits for a message to come through the serial stream.
        /// </summary>
        /// <param name="message">Message to look for.</param>
        /// <param name="timeout">Number of milliseconds to wait for the message.</param>
        ISerialRunnable WaitForMessage(string message, int timeout);

        /// <summary>
        /// Signals to launch the title.  If you want to launch the title after the System Config Tool has launched,
        /// call <see cref="WaitForSystemConfigTool"/> first to ensure progress is that far.
        /// </summary>
        /// <param name="titleId">Title Id of the game to launch.</param>
        ISerialRunnable LaunchTitle(string titleId);

        /// <summary>
        /// Signals to reboot the CAT-R and launch the title.
        /// </summary>
        /// <param name="titleId">Title Id of the game to launch.</param>
        ISerialRunnable LaunchTitleSlow(string titleId);

        /// <summary>
        /// Closes the serial port.
        /// </summary>
        ISerialStartable Stop();

        /// <summary>
        /// Simply performs an action.  Used only to keep the fluent API intact.
        /// </summary>
        /// <param name="message">Action to perform.</param>
        ISerialRunnable PerformAction(Action action);
    }

    /// <summary>
    /// Provides a set of base operations for starting up and configuring the serial port.
    /// </summary>
    public interface ISerialStartable
    {
        /// <summary>
        /// Opens the serial port and begins listening to incoming data.
        /// </summary>
        /// <param name="portNumber">COM port number.</param>
        ISerialRunnable Start(string portNumber);
    }

    /// <summary>
    /// Provides a set of helper methods and shortcuts for working with the serial device.
    /// </summary>
    public static class SerialExtensions
    {
        /// <summary>
        /// Waits for the System Config Tool to load.
        /// </summary>
        public static ISerialRunnable WaitForSystemConfigTool(this ISerialRunnable serialRunnable)
        {
            return serialRunnable.WaitForMessage(Serial.Messages.SysConfigEntry);
        }

        /// <summary>
        /// Simply prints a message to the console window.  Used to keep the fluent API intact.
        /// </summary>
        /// <param name="message">Message to print.</param>
        public static ISerialRunnable PrintMessage(this ISerialRunnable serialRunnable, string message)
        {
            return serialRunnable.PerformAction(() => {
                                                        if(!string.IsNullOrEmpty(message))
                                                        {
                                                            Console.WriteLine(message);
                                                        }
                                                      });
        }
    }


    /// <summary>
    /// Provides a set of operations for working with the serial port out from a devkit.
    /// </summary>
    public class Serial : ISerialDevice
    {
        /// <summary>
        /// Defines a set of known messages that are output from the devkit.
        /// </summary>
        public static class Messages
        {
            /// <summary>
            /// Output string from the devkit that indicates the System Config Tool has started.
            /// </summary>
            public const string SysConfigEntry = "sysconf: enter";

            /// <summary>
            /// Message &quot;ACP: initialized&quot;.
            /// </summary>
            public const string AcpInitialized = "ACP: initialized";

            /// <summary>
            /// Message &quot;VPAD Init end&quot;.
            /// </summary>
            public static readonly string VpadInitEnd = CatToucan.Terms.VPAD_INIT_END;

        }

        /// <summary>
        /// Cafe new line in serial is \r; not \r\n and not \n.
        /// </summary>
        private const string CafeNewLine = "\r";

        /// <summary>
        /// Amount of time to wait a message (1 min).
        /// </summary>
        private const int DefaultMessageTimeout = 1000 * 60;

        /// <summary>
        /// 5 second read timeout.  Used in the event the serial stream gets cut and does not send <see cref="CafeNewLine"/>.
        /// </summary>
        private const int ReadTimeout = 1000 * 5;

        private const int DevKitBaudRate = 57600;
        private const Parity DevKitParity = Parity.None;
        private const int DevKitDataBits = 8;
        private const StopBits DevKitStopBits = StopBits.One;

        private SerialPort _serialPort;

        private IDictionary<string, ManualResetEvent> _messages;

        private readonly object _messageLock = new object();
        private readonly object _readLock = new object();

        /// <summary>
        /// Gets or sets whether to display the serial output.
        /// </summary>
        public bool DisplayOutput { get; set; }

        /// <summary>
        /// Gets an instance to the serial device.
        /// </summary>
        public static ISerialDevice Device { get; private set; }

        static Serial()
        {
            Device = new Serial();
        }

        private Serial() { }

        /// <summary>
        /// Opens the serial port and begins listening to incoming data.
        /// </summary>
        /// <param name="portNumber">COM port number.</param>
        public ISerialRunnable Start(string portNumber)
        {
            if(_serialPort != null)
            {
                return this;
            }

            _serialPort = new SerialPort(string.Format("COM{0}", portNumber),
                                         DevKitBaudRate,
                                         DevKitParity,
                                         DevKitDataBits,
                                         DevKitStopBits);
            _serialPort.NewLine = CafeNewLine;
            _serialPort.ReadTimeout = ReadTimeout; //crucial because default is Infinite, could create a deadlock
            _serialPort.DataReceived += DataReceivedHandler;

            _messages = new Dictionary<string, ManualResetEvent>();

            _serialPort.Open();

            Console.WriteLine(string.Format("Serial communication started on COM{0}", portNumber));

            return this;
        }

        /// <summary>
        /// Closes the serial port.
        /// </summary>
        public ISerialStartable Stop()
        {
            if(_serialPort == null)
            {
                return this;
            }

            lock (_readLock)
            {

                _serialPort.DataReceived -= DataReceivedHandler;

                //this .NET bug can cause Close/Dispose to hang without throwing an exception.
                //for now, the serial port should not be started and stopped more than one
                //we won't explicitly close and let Windows handle freeing up the device on exit
                //https://connect.microsoft.com/VisualStudio/feedback/details/140018/serialport-crashes-after-disconnect-of-usb-com-port
                //_serialPort.Close();
                //_serialPort.Dispose();
                _serialPort = null;

                foreach(var message in _messages)
                {
                    message.Value.Set();
                    message.Value.Close();
                }

                _messages.Clear();
                _messages = null;

            }

            Console.WriteLine("Serial communication stopped.");

            return this;
        }

        /// <summary>
        /// Signals to launch the title.  If you want to launch the title after the System Config Tool has launched,
        /// call <see cref="WaitForSystemConfigTool"/> first to ensure progress is that far.
        /// </summary>
        /// <param name="titleId">Title Id of the game to launch.</param>
        public ISerialRunnable LaunchTitle(string titleId)
        {
            if (string.IsNullOrEmpty(titleId))
            {
                throw new ArgumentNullException(titleId);
            }

            ValidateSerialPort();

            Console.WriteLine(string.Format("Launching title {0}", titleId));
            _serialPort.WriteLine(string.Format("cos launch 0x{0} 0x{1}", titleId.Substring(0, 8), titleId.Substring(8)));

            return this;
        }

        /// <summary>
        /// Signals to reboot the CAT-R and launch the title.
        /// </summary>
        /// <param name="titleId">Title Id of the game to launch.</param>
        public ISerialRunnable LaunchTitleSlow(string titleId)
        {
            if (string.IsNullOrEmpty(titleId))
            {
                throw new ArgumentNullException(titleId);
            }

            ValidateSerialPort();

            Console.WriteLine(string.Format("Launching title {0}", titleId));
            _serialPort.WriteLine(string.Format("cos slowlaunch 0x{0}", titleId));

            return this;
        }

        /// <summary>
        /// Waits for a message to come through the serial stream.
        /// </summary>
        /// <param name="message">Message to look for.</param>
        public ISerialRunnable WaitForMessage(string message)
        {
            return WaitForMessage(message, DefaultMessageTimeout);
        }

        /// <summary>
        /// Waits for a message to come through the serial stream.
        /// </summary>
        /// <param name="message">Message to look for.</param>
        /// <param name="timeout">Number of milliseconds to wait for the message.</param>
        public ISerialRunnable WaitForMessage(string message, int timeout)
        {
            ValidateSerialPort();

            var messageEvent = new ManualResetEvent(false);

            lock(_messageLock)
            {
                _messages.Add(message, messageEvent);
            }

            if(!messageEvent.WaitOne(timeout))
            {
                Console.WriteLine(string.Format("Could not find message '{0}'", message));
            }

            return this;
        }

        /// <summary>
        /// Simply performs an action.  Used only to keep the fluent API intact.
        /// </summary>
        /// <param name="message">Action to perform.</param>
        public ISerialRunnable PerformAction(Action action)
        {
            if(action != null)
            {
                action();
            }

            return this;
        }

        /// <summary>
        /// Checks that the serial port is open and working, otherwise throws an exception.
        /// </summary>
        private void ValidateSerialPort()
        {
            if (_serialPort == null || !_serialPort.IsOpen)
            {
                throw new Exception("Serial communication has not been started.");
            }
        }

        /// <summary>
        /// Incoming data handler.  Listens for incoming cues to perform certain actions.
        /// </summary>
        /// <param name="sender">Serial Port.</param>
        /// <param name="e">Data received.</param>
        private void DataReceivedHandler(object sender, SerialDataReceivedEventArgs e)
        {
            lock (_readLock)
            {
                //the lock and subsequent check for serialport is to ensure that the port
                //is not taken down during a read, which will result in an exception.  This
                //can happen because the two operations happen on separate threads.
                if(_serialPort == null)
                {
                    return;
                }

                try
                {
                    var line = _serialPort.ReadLine();

                    if (DisplayOutput)
                    {
                        Console.WriteLine(line);
                    }

                    lock(_messageLock)
                    {
                        var message = _messages.Keys.FirstOrDefault(m => line.Contains(m));

                        if(message != null)
                        {
                            _messages[message].Set();
                            _messages.Remove(message);
                        }
                    }
                }
                catch (TimeoutException)
                {
                    //do nothing, this could happen if the serial stream was cut and doesn't send a NewLine
                    //like when a title is launched
                }
            }
        }
    }
}