:mod:`ps2io`
============

.. py:module:: ps2io

.. autoapi-nested-parse::

   Support for PS/2 protocol

   The `ps2io` module contains classes to provide PS/2 communication.

   .. warning:: This module is not available in some SAMD21 builds. See the
     :ref:`module-support-matrix` for more info.

   All classes change hardware state and should be deinitialized when they
   are no longer needed if the program continues after use. To do so, either
   call :py:meth:`!deinit` or use a context manager. See
   :ref:`lifetime-and-contextmanagers` for more info.



.. raw:: html

    <p>
    <details>
    <summary>Available on these boards</summary>
    <ul>
    <li> AITHinker ESP32-C3S_Kit
    <li> ATMegaZero ESP32-S2
    <li> Adafruit EdgeBadge
    <li> Adafruit Feather ESP32-S2 TFT
    <li> Adafruit Feather ESP32S2
    <li> Adafruit Feather M4 CAN
    <li> Adafruit Feather M4 Express
    <li> Adafruit FunHouse
    <li> Adafruit Grand Central M4 Express
    <li> Adafruit Hallowing M4 Express
    <li> Adafruit ItsyBitsy M4 Express
    <li> Adafruit MagTag
    <li> Adafruit Matrix Portal M4
    <li> Adafruit Metro ESP32S2
    <li> Adafruit Metro M4 Airlift Lite
    <li> Adafruit Metro M4 Express
    <li> Adafruit Monster M4SK
    <li> Adafruit PyGamer
    <li> Adafruit PyPortal
    <li> Adafruit PyPortal Pynt
    <li> Adafruit PyPortal Titano
    <li> Adafruit Pybadge
    <li> Adafruit QT Py ESP32S2
    <li> Adafruit Trellis M4 Express
    <li> AloriumTech Evo M51
    <li> Artisense Reference Design RD00
    <li> BDMICRO VINA-D51
    <li> BastWiFi
    <li> CP32-M4
    <li> Capable Robot Programmable USB Hub
    <li> CircuitBrains Deluxe
    <li> CrumpS2
    <li> DynOSSAT-EDU-OBC
    <li> ESP 12k NodeMCU
    <li> Feather ESP32S2 without PSRAM
    <li> FeatherS2
    <li> FeatherS2 Neo
    <li> FeatherS2 PreRelease
    <li> Franzininho WIFI w/Wroom
    <li> Franzininho WIFI w/Wrover
    <li> Gravitech Cucumber M
    <li> Gravitech Cucumber MS
    <li> Gravitech Cucumber R
    <li> Gravitech Cucumber RS
    <li> HMI-DevKit-1.1
    <li> Kaluga 1
    <li> LILYGO TTGO T8 ESP32-S2 w/Display
    <li> LoC BeR M4 base board
    <li> MORPHEANS MorphESP-240
    <li> MicroDev microC3
    <li> MicroDev microS2
    <li> Mini SAM M4
    <li> Oak Dev Tech PixelWing ESP32S2
    <li> Robo HAT MM1 M4
    <li> S2Mini
    <li> S2Pico
    <li> SAM32v26
    <li> Saola 1 w/Wroom
    <li> Saola 1 w/Wrover
    <li> Seeeduino Wio Terminal
    <li> Silicognition LLC M4-Shim
    <li> SparkFun MicroMod SAMD51 Processor
    <li> SparkFun Thing Plus - SAMD51
    <li> TG-Boards' Datalore IP M4
    <li> Targett Module Clip w/Wroom
    <li> Targett Module Clip w/Wrover
    <li> The Open Book Feather
    <li> Thingz - Galaxia
    <li> TinyS2
    <li> UARTLogger II
    <li> nanoESP32-S2  w/Wrover
    <li> nanoESP32-S2 w/Wroom
    </ul>
    </details>
    </p>




.. py:class:: Ps2(data_pin: microcontroller.Pin, clock_pin: microcontroller.Pin)

   Communicate with a PS/2 keyboard or mouse

   Ps2 implements the PS/2 keyboard/mouse serial protocol, used in
   legacy devices. It is similar to UART but there are only two
   lines (Data and Clock). PS/2 devices are 5V, so bidirectional
   level converters must be used to connect the I/O lines to pins
   of 3.3V boards.

   Create a Ps2 object associated with the given pins.

   :param ~microcontroller.Pin data_pin: Pin tied to data wire.
   :param ~microcontroller.Pin clock_pin: Pin tied to clock wire.
     This pin must support interrupts.

   Read one byte from PS/2 keyboard and turn on Scroll Lock LED::

     import ps2io
     import board

     kbd = ps2io.Ps2(board.D10, board.D11)

     while len(kbd) == 0:
         pass

     print(kbd.popleft())
     print(kbd.sendcmd(0xed))
     print(kbd.sendcmd(0x01))

   .. py:method:: deinit() -> None

      Deinitialises the Ps2 and releases any hardware resources for reuse.


   .. py:method:: __enter__() -> Ps2

      No-op used by Context Managers.


   .. py:method:: __exit__() -> None

      Automatically deinitializes the hardware when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.


   .. py:method:: popleft() -> int

      Removes and returns the oldest received byte. When buffer
      is empty, raises an IndexError exception.


   .. py:method:: sendcmd(byte: int) -> int

      Sends a command byte to PS/2. Returns the response byte, typically
      the general ack value (0xFA). Some commands return additional data
      which is available through :py:func:`popleft()`.

      Raises a RuntimeError in case of failure. The root cause can be found
      by calling :py:func:`clear_errors()`. It is advisable to call
      :py:func:`clear_errors()` before :py:func:`sendcmd()` to flush any
      previous errors.

      :param int byte: byte value of the command


   .. py:method:: clear_errors() -> None

      Returns and clears a bitmap with latest recorded communication errors.

      Reception errors (arise asynchronously, as data is received):

      0x01: start bit not 0

      0x02: timeout

      0x04: parity bit error

      0x08: stop bit not 1

      0x10: buffer overflow, newest data discarded

      Transmission errors (can only arise in the course of sendcmd()):

      0x100: clock pin didn't go to LO in time

      0x200: clock pin didn't go to HI in time

      0x400: data pin didn't ACK

      0x800: clock pin didn't ACK

      0x1000: device didn't respond to RTS

      0x2000: device didn't send a response byte in time


   .. py:method:: __bool__() -> bool


   .. py:method:: __len__() -> int

      Returns the number of received bytes in buffer, available
      to :py:func:`popleft()`.