ps2_Keyboard.h

Go to the documentation of this file.

/*
Copyright (C) 2017 Steve Benz <s8878992@hotmail.com>

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
USA
*/
#pragma once

#if defined(ARDUINO) && ARDUINO >= 100
#include "Arduino.h" // for attachInterrupt, FALLING, HIGH & LOW
#else
#include "WProgram.h"
#endif
#include <stdint.h>
#include <util/atomic.h>
#include "ps2_NullDiagnostics.h"
#include "ps2_KeyboardLeds.h"
#include "ps2_KeyboardOutput.h"
#include "ps2_TypematicRate.h"
#include "ps2_TypematicStartDelay.h"
#include "ps2_ScanCodeSet.h"
#include "ps2_Parity.h"
#include "ps2_KeyboardOutputBuffer.h"

namespace ps2 {

    /*
     * Excellent references:
     *  http://www.computer-engineering.org/ps2keyboard/
     */

    template<int DataPin, int ClockPin, int BufferSize = 16, typename Diagnostics = NullDiagnostics>
    class Keyboard {
        static const uint8_t immediateResponseTimeInMilliseconds = 10;

        Diagnostics *diagnostics;

        // These are not marked as volatile because they are only modified in the interrupt
        // handler and at startup (before the interrupt handler is enabled).
        uint8_t ioByte = 0;
        uint8_t bitCounter = 0;
        uint32_t failureTimeMicroseconds = 0;
        uint32_t lastReadInterruptMicroseconds = 0;
        Parity parity = Parity::even;
        bool receivedHasFramingError = false;

        // This guy is marked volatile because it's exchanged between the interrupt handler and normal code.
        KeyboardOutputBuffer<BufferSize, Diagnostics> inputBuffer;

        // Commands sent from the host to the ps2 keyboard.  Private to this class because
        //  the point of the class is to encapsulate the protocol.
        enum class ps2CommandCode : uint8_t {
            reset = 0xff,
            resend = 0xfe,
            disableBreakAndTypematicForSpecificKeys = 0xfd,
            disableTypematicForSpecificKeys = 0xfc,
            disableBreaksForSpecificKeys = 0xfb,
            enableBreakAndTypeMaticForAllKeys = 0xfa,
            disableBreakAndTypematicForAllKeys = 0xf9,
            disableTypematicForAllKeys = 0xf8,
            disableBreaksForAllKeys = 0xf7,
            useDefaultSettings = 0xf6,
            disable = 0xf5,
            enable = 0xf4,
            setTypematicRate = 0xf3,
            readId = 0xf2,
            setScanCodeSet = 0xf0,
            echo = 0xee,
            setLeds = 0xed,
        };

        void readInterruptHandler() {
            // The timing of the PS2 keyboard is such that you really need to read the data
            // line just as fast as possible.  If you do it with digitalRead, it'll work right
            // almost all the time (like one character in 100 will suffer a failure - with the
            // keyboards I have to-hand.)
            //
            // Although this looks fantastically more complicated than plain digitalRead, the
            // instruction count is lower.  It'd be even lower if the methods listed here were
            // implemented a little better (e.g. as template methods rather than macros).
            uint8_t dataPinValue = (*portInputRegister(digitalPinToPort(DataPin)) & digitalPinToBitMask(DataPin)) ? 1 : 0; // ==digitalRead(DataPin);

            lastReadInterruptMicroseconds = micros();
            // TODO: Perhaps there should be code here that detects if bitCounter > 0 && the time since
            //  the last read interrupt is > a millisecond and, if so, log that and reset
            //  bitCounter.
            //
            //  It doesn't really need doing principally because the error-recovery code is already
            //  going to catch this (even if it doesn't do it very well).  If you have other interrupts
            //  in your system and they happen with concurrently with the keyboard, I think it's unlikely
            //  you'll ever be able to craft a foolproof system.  That since the "Ack" request only
            //  gets the previous byte.  What we'd really need to recover would be something that asks
            //  the keyboard for all keys currently pressed, and there's no such thing.
            //
            //  But perhaps I'm wrong and it's not as bad as all that.

            switch (bitCounter)
            {
            case 0:
                if (dataPinValue == 0) {
                    receivedHasFramingError = false;
                }
                else {
                    this->diagnostics->packetDidNotStartWithZero();

                    // If we get a failure here, it should mean that previous byte is
                    // not actually framed correctly and the stop bit and parity bit somehow
                    // matched our expectations (or maybe they didn't and we got here anyway?)
                    receivedHasFramingError = true;
                    failureTimeMicroseconds = lastReadInterruptMicroseconds;
                }
                ++bitCounter;
                parity = Parity::even;
                break;
            case 1:
            case 2:
            case 3:
            case 4:
            case 5:
            case 6:
            case 7:
            case 8:
                if (dataPinValue)
                {
                    ioByte |= (1 << (bitCounter - 1));
                    parity ^= 1;
                }
                ++bitCounter;
                break;
            case 9:
                if (parity != (Parity)dataPinValue) {
                    this->diagnostics->parityError();
                    receivedHasFramingError = true;
                    failureTimeMicroseconds = lastReadInterruptMicroseconds;
                }
                ++bitCounter;
                break;
            case 10:
                if (dataPinValue == 0) {
                    this->diagnostics->packetDidNotEndWithOne();
                    receivedHasFramingError = true;
                    failureTimeMicroseconds = lastReadInterruptMicroseconds;
                }

                if (!receivedHasFramingError) {
                    this->diagnostics->receivedByte(ioByte);
                    this->inputBuffer.push((KeyboardOutput)ioByte);
                }
                bitCounter = 0;
                ioByte = 0;
            }
        }

        void writeInterruptHandler() {
            int valueToSend;

            switch (bitCounter)
            {
            case 0:
                ++bitCounter;
                break;
            case 1:
            case 2:
            case 3:
            case 4:
            case 5:
            case 6:
            case 7:
            case 8:
                valueToSend = (this->ioByte & (1 << (bitCounter - 1))) ? HIGH : LOW;
                digitalWrite(DataPin, valueToSend);
                parity ^= valueToSend;
                ++bitCounter;
                break;
            case 9:
                digitalWrite(DataPin, (uint8_t)parity);
                ++bitCounter;
                break;
            case 10:
                pinMode(DataPin, INPUT_PULLUP);
                ++bitCounter;
                break;
            case 11:
                if (digitalRead(DataPin) != LOW) {
                    // It'd be better to actually resend, but I don't think it's a thing,
                    //  and it seems impossible to test anyway.
                    this->diagnostics->sendFrameError();
                }

                enableReadInterrupts();
                break;
            }
        }

        void sendByte(uint8_t byte1) {
            // ISSUE:  If we really want to be tight about it, we should check to see if the keyboard
            //   is already in the middle of transmitting something before we launch into this.

            detachInterrupt(digitalPinToInterrupt(ClockPin));

            // Inhibit communication by pulling Clock low for at least 100 microseconds.
            pinMode(ClockPin, OUTPUT);
            digitalWrite(ClockPin, LOW);
            delayMicroseconds(120);

            // Make sure when interrupts resume, we start in the right state - note that we
            //  start sending data immediately on the first byte, because we will initiate
            //  the start bit in this clock pulse.
            this->receivedHasFramingError = false;
            this->inputBuffer.clear();
            this->bitCounter = 0;
            this->parity = Parity::even;
            this->ioByte = byte1;
            attachInterrupt(digitalPinToInterrupt(ClockPin), Keyboard::staticWriteInterruptHandler, FALLING);

            // Apply "Request-to-send" by pulling Data low, then release Clock.
            pinMode(DataPin, OUTPUT);
            digitalWrite(DataPin, LOW);
            pinMode(ClockPin, INPUT_PULLUP);
        }

        void enableReadInterrupts() {
            this->receivedHasFramingError = false;
            this->bitCounter = 0;
            this->ioByte = 0;
            this->parity = Parity::even;
            this->inputBuffer.clear(); // gratuitious?  Probably...

            attachInterrupt(digitalPinToInterrupt(ClockPin), Keyboard::staticReadInterruptHandler, FALLING);
        }

        static Keyboard *instance;

        static void staticReadInterruptHandler() {
            instance->readInterruptHandler();
        }

        static void staticWriteInterruptHandler() {
            instance->writeInterruptHandler();
        }

        KeyboardOutput expectResponse(uint16_t timeoutInMilliseconds = immediateResponseTimeInMilliseconds)
        {
            unsigned long startMilliseconds = millis();
            unsigned long stopMilliseconds = startMilliseconds + timeoutInMilliseconds;
            unsigned long nowMilliseconds;
            KeyboardOutput actualResponse;
            do
            {
                actualResponse = this->inputBuffer.peek();
                if (actualResponse == KeyboardOutput::none && this->receivedHasFramingError) {
                    actualResponse = KeyboardOutput::garbled;
                    // Note that clearing this is intended to prevent future polling from trying to get the
                    //  bad character re-sent, but it might not work, depending on the nature of the error.
                    //  Future interrupts could set it again.
                    this->receivedHasFramingError = false;
                }
                nowMilliseconds = millis();
            } while (actualResponse == KeyboardOutput::none && (nowMilliseconds < stopMilliseconds || (stopMilliseconds < startMilliseconds && startMilliseconds <= nowMilliseconds)));

            if (actualResponse == KeyboardOutput::none) {
                this->diagnostics->noResponse(KeyboardOutput::none);
            }
            return actualResponse;
        }

        bool expectResponse(KeyboardOutput expectedResponse, uint16_t timeoutInMilliseconds = immediateResponseTimeInMilliseconds) {
            KeyboardOutput actualResponse = expectResponse(timeoutInMilliseconds);

            if (actualResponse == KeyboardOutput::none) {
                // diagnostics already reported
                return false;
            }
            else if ( actualResponse != expectedResponse ) {
                this->diagnostics->incorrectResponse(actualResponse, expectedResponse);
                return false;
            }
            else {
                this->inputBuffer.pop();
                return true;
            }
        }

        bool expectAck() {
            return this->expectResponse(KeyboardOutput::ack);
        }

        bool sendCommand(ps2CommandCode command) {
            return this->sendData((byte)command);
        }

        bool sendCommand(ps2CommandCode command, byte data) {
            return this->sendCommand(command)
                && this->sendData(data);
        }

        bool sendCommand(ps2CommandCode command, const byte *data, int numBytes) {
            if (!this->sendCommand(command)) {
                return false;
            }
            for (int i = 0; i < numBytes; ++i) {
                if (!this->sendData(data[i])) {
                    return false;
                }
            }
            return true;
        }

        bool sendData(byte data) {
            this->diagnostics->sentByte(data);
            this->sendByte(data);
            bool isOk = this->expectAck();
            if (!isOk)
            {
                this->enableReadInterrupts();
            }
            return isOk;
        }

        void sendNack() {
            this->diagnostics->sentByte((byte)ps2CommandCode::resend);
            this->sendByte((byte)ps2CommandCode::resend);
        }

    public:
        Keyboard(Diagnostics &diagnostics = *Diagnostics::defaultInstance())
            : inputBuffer(diagnostics)
        {
            this->diagnostics = &diagnostics;
            instance = this;
        }

        void begin() {
            pinMode(ClockPin, INPUT_PULLUP);
            pinMode(DataPin, INPUT_PULLUP);

            // If the pin that support PWM output, we need to turn it off
            // before getting a digital reading.  DigitalRead does that
            digitalRead(DataPin);

            this->enableReadInterrupts();
        }

        bool awaitStartup(uint16_t timeoutInMillis = 750) {
            return this->expectResponse(KeyboardOutput::batSuccessful, timeoutInMillis);
        }

        KeyboardOutput readScanCode() {
            KeyboardOutput code = this->inputBuffer.pop();

            if (code == KeyboardOutput::none && this->receivedHasFramingError)
            {
                // NACK's affect what the device perceives as the last character sent, so if we
                //  interrupt immediately, it might decide to send the last scan code (which we
                //  already have) again.  The clock is between 17KHz and 10KHz, so the fastest
                //  send time for the 12 bits is going to be around 12*1000000/17000 700us and the
                //  slowest would be 1200us.  Again, that's the full cycle.  Most of the errors
                //  are going to be found at the parity & stop bit, so we'll wait 200us, as a guess,
                //  before asking for a retry.
                //
                // In hindsight, I think likely the most effective way to do error detection would
                //  be to wait for a certain amount of time after the last read interrupt when a
                //  failure has previously been detected.  For that to work, then when the keyboard
                //  sends a multi-byte sequence, there'd have to be a pause between one byte and
                //  the next; I haven't validated that such a pause actually exists, however.
                //
                // The other concern is how to ensure that we can get Arduino-time during that
                //  window; it'll be hard to guarantee that in a general purpose library.
                if (failureTimeMicroseconds + 200 > micros()) {
                    return KeyboardOutput::none;
                }
                if (this->bitCounter > 3) {
                    this->sendNack();
                }
                else {
                    this->diagnostics->clockLineGlitch(this->bitCounter);
                    this->receivedHasFramingError = false;
                    this->bitCounter = 0;
                    this->ioByte = 0;
                    this->parity = Parity::even;
                }
                return KeyboardOutput::garbled;
            }
            else if (code == KeyboardOutput::batSuccessful) {
                // The keyboard will send either batSuccessful or batFailure on startup.
                //   The way this class is structured, we can't really be sure that begin()
                //   will be called immediately after power-up, nor can we be sure that the
                //   Arduino wasn't just reset (while the keyboard had power the whole time).
                //   So we can't write code in begin() that just waits for the message.
                //   We could have a flag that is true until the first action is taken
                //   with the keyboard, but that seems needlessly wasteful.
                code = this->inputBuffer.pop();
            }
            else if (code == KeyboardOutput::batFailure) {
                diagnostics->startupFailure();
                code = this->inputBuffer.pop();
            }

            return code;
        }

        bool sendLedStatus(KeyboardLeds ledStatus)
        {
            return sendCommand(ps2CommandCode::setLeds, (byte)ledStatus);
        }

        bool reset(uint16_t timeoutInMillis = 1000) {
            this->inputBuffer.clear();
            this->sendCommand(ps2CommandCode::reset);
            return this->expectResponse(KeyboardOutput::batSuccessful, timeoutInMillis);
        }

        uint16_t readId() {
            this->sendCommand(ps2CommandCode::readId);
            KeyboardOutput response = this->expectResponse();
            if (response == KeyboardOutput::none) {
                return 0xffff;
            }
            this->inputBuffer.pop();
            uint16_t id = ((uint8_t)response) << 8;
            response = this->expectResponse();
            if (response == KeyboardOutput::none) {
                return 0xffff;
            }
            this->inputBuffer.pop();
            id |= (uint8_t)response;
            return id;
        }

        ScanCodeSet getScanCodeSet() {
            if (!this->sendCommand(ps2CommandCode::setScanCodeSet, 0)) {
                return ScanCodeSet::error;
            }
            ScanCodeSet result = (ScanCodeSet)this->expectResponse();
            if (result == ScanCodeSet::pcxt || result == ScanCodeSet::pcat || result == ScanCodeSet::ps2) {
                this->inputBuffer.pop();
                return result;
            }
            else {
                return ScanCodeSet::error;
            }
        }

        bool setScanCodeSet(ScanCodeSet newScanCodeSet) {
            return this->sendCommand(ps2CommandCode::setScanCodeSet, (byte)newScanCodeSet);
        }

        bool echo() {
            this->sendByte((byte)ps2CommandCode::echo);
            return this->expectResponse(KeyboardOutput::echo);
        }

        bool setTypematicRateAndDelay(TypematicRate rate, TypematicStartDelay startDelay) {
            byte combined = (byte)rate | (((byte)startDelay) << 4);
            return this->sendCommand(ps2CommandCode::setTypematicRate, combined);
        }

        bool resetToDefaults()
        {
            return this->sendCommand(ps2CommandCode::useDefaultSettings);
        }

        bool enable() { return this->sendCommand(ps2CommandCode::enable); }

        bool disable() { return this->sendCommand(ps2CommandCode::disable); }

        bool enableBreakAndTypematic() {
            return this->sendCommand(ps2CommandCode::enableBreakAndTypeMaticForAllKeys);
        }

        bool disableBreakCodes() {
            return this->sendCommand(ps2CommandCode::disableBreaksForAllKeys);
        }

        bool disableBreakCodes(const byte *specificKeys, int numKeys) {
            return this->sendCommand(ps2CommandCode::disableBreaksForSpecificKeys, specificKeys, numKeys);
        }

        bool disableTypematic() {
            return this->sendCommand(ps2CommandCode::disableTypematicForAllKeys);
        }

        bool disableBreakAndTypematic() {
            return this->sendCommand(ps2CommandCode::disableBreakAndTypematicForAllKeys);
        }

        bool disableTypematic(const byte *specificKeys, int numKeys) {
            return this->sendCommand(ps2CommandCode::disableTypematicForSpecificKeys, specificKeys, numKeys);
        }

        bool disableBreakAndTypematic(const byte *specificKeys, int numKeys) {
            return this->sendCommand(ps2CommandCode::disableBreakAndTypematicForSpecificKeys, specificKeys, numKeys);
        }
    };

    template<int DataPin, int ClockPin, int BufferSize, typename Diagnostics>
    Keyboard<DataPin, ClockPin, BufferSize, Diagnostics> *Keyboard<DataPin, ClockPin, BufferSize, Diagnostics>::instance = nullptr;
}