{"id":1978,"date":"2022-08-29T13:04:24","date_gmt":"2022-08-29T12:04:24","guid":{"rendered":"https:\/\/pmortensen.eu\/world2\/?p=1978"},"modified":"2023-05-27T17:50:27","modified_gmt":"2023-05-27T16:50:27","slug":"controlling-leds-on-ps-2-keyboards","status":"publish","type":"post","link":"https:\/\/pmortensen.eu\/world2\/2022\/08\/29\/controlling-leds-on-ps-2-keyboards\/","title":{"rendered":"Controlling the three LEDs on PS\/2 keyboards"},"content":{"rendered":"

When repurposing old (or new) PS\/2<\/a> keyboards as macro keyboards (because they are much easier to interface with than USB keyboards), there are three free LEDs<\/a> that can also be repurposed, e.g., for various status purposes (say, indicating a macro key action is in progress or indicating a mode<\/em><\/strong> the macro keyboard is in, like an extra slow macro key mode or an extra fast macro key mode. Or\/and special flashing in some error conditions).<\/p>\n

Here it is documented how these LEDs can be controlled.<\/p>\n

Hardware requirements<\/h2>\n

There aren’t any hardware requirements! At least not if using a standard (5 V) microcontroller to interface to the PS\/2 keyboard. The required open collector<\/a> output can be simulated<\/em><\/strong> by changing the I\/O port to output<\/em><\/strong> (with a value of 0) for the (driving) ‘0’<\/em><\/strong> and changing the I\/O port to input<\/em><\/strong> for the ‘1’<\/em><\/strong> (the pull-up resistors in the keyboard takes care of the proper voltage level). In essence, the I\/O port direction becomes the signal<\/em><\/strong> as seen from the microcontroller side. This is similar to how it was implemented in hardware for the original IBM PC.<\/p>\n

There needs to be hardware that can pull the two signal lines (CLK<\/a> and DATA<\/a>) low<\/em>, but not<\/em><\/strong> pull them high (they must not be driven high as that would cause a conflict when the keyboard sends information in the other direction\u2014the normal operation of the keyboard when the user presses keys). This is similar to how an SPI<\/a> or I\u00b2C<\/a> interface works.<\/p>\n

A naive approach (or if the I\/O direction can not be changed), is to implement it with discrete BJTs<\/a> (open collector<\/a>), FETs<\/a> (open drain<\/a>), using TTL<\/a> chips or CMOS<\/a> chips. In all cases there must be a pull-up resistor<\/a> somewhere (that is already the case for a PS\/2 keyboard), and it should have a sufficiently low value to satisfy timing requirements. In the original IBM PC, a TTL 74LS125<\/a> with three-state<\/a> outputs was used for this purpose. The input was fixed to ground, and the controlling signal was to the (inverting) enable pin. The pull-up resistor was 4.7 k\u03a9.<\/p>\n

<\/p>\n

<\/p>\n

Note that the BJT solution is inverting<\/em> (e.g., a high on the I\/O port used to drive the circuit for CLK will result in a (driving) low on CLK on the PS\/2 interface side), so this must be accounted for, e.g., in the software. A floating input to the BJT circuit is OK, but it is best to set it to a driving low when the microcontroller program initialises the hardware (I\/O ports). Note that many diagrams, incl. in the first source, do not show the base resistor. It is required<\/em> to limit the current; otherwise, the microcontroller may be damaged. Its value can be on the order of 10 k\u03a9.<\/p>\n

Note that if the CLK signal is connected to an interrupt capable pin, the software has to account for that; asserting the CLK will generate an interrupt that must be ignored (to not be interpreted as something the keyboard sends).<\/p>\n

Protocol, bit level<\/h2>\n

Before sending the first bit to the keyboard, a certain protocol is required<\/em><\/strong> to initiate<\/em> sending information to the keyboard:<\/p>\n

    \n
  1. Hold CLK low for at least 100 \u00b5sec (more than one bit time), for instance 150 \u00b5sec (0.15 millisecond).<\/li>\n
  2. Assert the DATA signal low<\/li>\n
  3. Release the CLK signal (setting it to high)<\/li>\n
  4. Hold the DATA signal low until the keyboard starts producing clock signals<\/em><\/strong> on CLK. That is, a falling edge on CLK. This can take up to a whopping 6 ms (6000 \u00b5sec) (but it can be much shorter), with some keyboards not going over 750 \u00b5sec. 750 \u00b5sec corresponds to about 11 bit times (a full frame). Note that the waiting for the falling edge on CLK is automatically included in sending the first bit (see below).<\/li>\n<\/ol>\n

    The keyboard samples on the rising edge<\/em> of the CLK signal (in normal operation, when the keyboard sends key codes as a result of key presses, the significant edge is the falling edge), so the DATA signal can be set up shortly after the falling edge of the CLK signal.<\/p>\n

    So the sequence to send a single bit (say, a data bit) is:<\/p>\n

      \n
    1. Wait for a falling edge of CLK<\/li>\n
    2. Set up the DATA signal<\/li>\n
    3. Nothing more to do, other than wait! Sufficient time must pass so that the data is sampled by the keyboard on the rising edge of CLK (on the order of 50 \u00b5sec later)<\/li>\n<\/ol>\n

      Note: For 1., if implemented in a bit-banging busy wait way (the most common) with a microcontroller, it is crucial to have a timeout, otherwise the program may hang, e.g., if the keyboard is not connected…<\/p>\n

      Protocol, byte level<\/h2>\n

      Similar (but not identical) to asynchronous serial communication<\/a>, when sending to the keyboard, a data frame consists of:<\/p>\n

        \n
      1. 8 data bits with the least significant bit (LSB<\/a>) send first<\/li>\n
      2. Parity bit, always odd parity (an even<\/em><\/strong> number of ‘1’ data bits results in a parity bit of 1 (a more round-about way of saying it is that the number of ‘1’ bits, including the parity bit itself, is odd…))<\/li>\n
      3. Stop bit. Always ‘1’. This also frees up the DATA signal (as the next data bit will be from<\/em> the keyboard). This also marks the end of the time that the host will assert any of the signals.<\/li>\n
      4. Acknowledge bit. Always ‘0’. This is send from<\/em> the keyboard (reverse flow of information).\n

        Note 1: When sending to the keyboard, a start bit is not send (in contrast to when the keyboard is sending). There are still 11 pulses on CLK (corresponding to 11 bits), but that is due to the extra bit at the end, the acknowledge bit.
        \nOr an alternative interpretation is that the asserted low DATA line is some sort of start bit – but it is a very weird start bit (very long, variable length, up to about 90 bit times long (about 8 frames), and does not work unless CLK has the right polarities at the right times), and does not fit with how the rest of the bits are clocked (from the keyboard) – it could be interpreted as the host providing the first (rising) CLK edge, but that is a bit of a stretch.<\/p>\n

        Note 2: In most cases, after the keyboard has received a command byte, it will send back an acknowledge byte. Thus if we want to send more than one command byte (that is the case for setting the LEDs), we can’t send the second command byte immediately after the first. One way is to simply to ignore what the keyboard sends back and wait a sufficient amount of time before blindly sending the second command byte, say 2 ms (2000 \u00b5sec). It is not known how robust this method is. For instance, if the keyboard takes longer than expected to send the acknowledge byte for the first command byte, it could result in a transmit error and thus disabling the keyboard…<\/p>\n

        Note 3: When the keyboard sends, it also uses odd parity.<\/p>\n

        Parity bit<\/h3>\n

        The parity bit must be set correct. Otherwise, the keyboard will ignore the command byte.<\/p>\n

        Protocol, message level<\/h2>\n

        Only two commands are needed for this purpose, reset, 0xFF (not strictly necessary as power on does the same) and 0xED followed by a byte where the last three bits (bit 0, bit 1, and bit 2) represent the three LEDs:<\/p>\n