V1.0.7 Add SAMD1 and other tidy ups

Author: techpaul

README.md

@@ -1,6 +1,8 @@
 # PS2KeyAdvanced
 ## Arduino PS2 Keyboard FULL keyboard protocol support and full keys to integer coding
-**V1.0.6** January 2020 - Fix typos, correct keyboard reset status improve library.properties 
+**V1.0.7** February 2020 - Add notes for porting to other platforms
+
+V1.0.6 January 2020 - Fix typos, correct keyboard reset status improve library.properties 
 		   and additional reduction for easier platform handling
 
 V1.0.4 August 2018 - Minor reduction in available() method to remove redundant extra safety checks on buffers
@@ -15,8 +17,10 @@ For other versions that just read the keycodes for all keyboard types or allow y
 
 ### Platforms
 
-    Arduino AVR - tested on Uno and Mega 2560
-    Arduino SAM - tested on DUE
+-  Arduino AVR - tested on Uno and Mega 2560 (Users have tested on Teensy 2.0 and Teensy++ 2.0)
+-  Arduino SAM - tested on DUE
+
+See later for porting to other platforms
 
 ### Test Environment
 
@@ -44,20 +48,21 @@ For other versions that just read the keycodes for all keyboard types or allow y
 2. When using DUE or other boards with 3V3 I/O you MUST use a level translator FET or IC like Texas Instruments TXS0102 or similar as most keyboards not only operate at 5V but the two wire communications are pulled up by a resistor to 5V at the keyboard end.
 
 ### Introduction
-
 After looking round for suitable libraries I found most were lacking in functionality and high in code and data footprint, so I created a series of PS2 Keyboard libraries. This is the second which fully supports the PS2 Keyboard Protocol, even allowing you control of keyboard LEDs (some have 4 LEDs) and changing settings..
 
 The PS2 Keyboard interface is still needed for systems that have no USB and even if you have USB, you want it left for other uses.
 
 The PS2 Keyboard interface is a Bi-directional two wire interface with a clock line and a data line which you connect to your Arduino (see above), the keyboard protocol has many nuances all of which are used in the other libraries of this series. this library allows you to access the keycodes sent from a keyboard into its small buffer and read out the codes with simple methods.
 
 Returns any keypress as 16 bit integer, which includes a coded value for the key along with status for
+
    - Make/Break
    - CTRL, SHIFT, CAPS, ALT, GUI, ALT-GR Status
    - Alphanumeric/keyboard Function
    - 8 bit key code (defined in public header)
 
-  Fully featured PS2 keyboard library to provide
+Fully featured PS2 keyboard library to provide
+
     - All keys have a keycode (ESC, A-Z and 0-9 as ASCII equivalents)
     - All function (F1 to F24), multimedia and movement keys supported
     - Parity checking of data sent/received
@@ -74,20 +79,17 @@ Returns any keypress as 16 bit integer, which includes a coded value for the key
     - Handles NUM/SCROLL internally
 
 ### Installation
-
 Performed by standard zip file library inclusion into Arduino IDE
-
 ### Examples
-
 This library has THREE examples, from simplest to most complec -
 
   - SimpleTest that uses the serial port to output the converted codes received on every keystroke and auto-repeat.
   - advcodetest that uses serial port and some of the keys pressed to send commands back to the keyboard to see the responses for things like Reset keyboard, Read ID, change Typematic rate (auto-repeat).
   - KeyToLCD - Example that will allow you to display keyboard actions on LCD connected to Arduino and allow cursor movements to move the cursor on LCD, whilst also displaying strings for keys like ESC, TAB, F1 to F12
 
-
+## Porting to different boards or architectures
+See document Porting.md in extras folder for hints to assist in this process
 ### Contributor and Author Details
-
 Author Paul Carpenter, PC Services
 
 Web Site http://www.pcserviceselectronics.co.uk

examples/SimpleTest/SimpleTest.ino

@@ -139,7 +139,7 @@ uint16_t c;
 PS2KeyAdvanced keyboard;
 
 
-void setup()
+void setup( )
 {
 // Configure the keyboard library
 keyboard.begin( DATAPIN, IRQPIN );
@@ -148,12 +148,12 @@ Serial.println( "PS2 Advanced Key Simple Test:" );
 }
 
 
-void loop()
+void loop( )
 {
-if( keyboard.available() )
+if( keyboard.available( ) )
   {
   // read the next key
-  c = keyboard.read();
+  c = keyboard.read( );
   if( c > 0 )
     {
     Serial.print( "Value " );

examples/advcodetest/advcodetest.ino

@@ -55,7 +55,7 @@
    Clock pin from PS2 keyboard MUST be connected to an interrupt
    pin, these vary with the different types of Arduino
 
-  PS2KeyAdvanced requires both pins specified for begin()
+  PS2KeyAdvanced requires both pins specified for begin( )
 
   keyboard.begin( data_pin, irq_pin );
 
@@ -151,27 +151,36 @@ uint8_t repeats = 0;
 PS2KeyAdvanced keyboard;
 
 
-void setup()
+void setup( )
 {
 Serial.begin( 115200 );
 Serial.println( "PS2 Advanced Key - Advanced Test:" );
 
 // Configure the keyboard library
 keyboard.begin( DATAPIN, IRQPIN );
-keyboard.echo();              // ping keyboard to see if there
+keyboard.echo( );              // ping keyboard to see if there
 delay( 6 );
-c = keyboard.read();
-if( (c & 0xFF) == PS2_KEY_ECHO )
-  Serial.println( "Keyboard OK.." );
+c = keyboard.read( );
+if( (c & 0xFF) == PS2_KEY_ECHO 
+    || (c & 0xFF) == PS2_KEY_BAT )
+  Serial.println( "Keyboard OK.." );    // Response was Echo or power up
+else
+  if( ( c & 0xFF ) == 0 )
+    Serial.println( "Keyboard Not Found" );
+  else
+    {
+    Serial.print( "Invalid Code received of " );
+    Serial.println( c, HEX );
+    }
 }
 
 
-void loop()
+void loop( )
 {
-if( keyboard.available() )
+if( keyboard.available( ) )
   {
   // read the next key
-  c = keyboard.read();
+  c = keyboard.read( );
   if( ( c & 0xFF ) > 0 )
     Serial.println( c , HEX );
   /* now do something with keys entered results on serial monitor */
@@ -180,24 +189,24 @@ if( keyboard.available() )
       {
       case PS2_KEY_R:
                    Serial.println( "Reset" );
-                   keyboard.resetKey();  // Reset keyboard
+                   keyboard.resetKey( );  // Reset keyboard
                    break;
       case PS2_KEY_S:
                    Serial.println( "Get Scancode set in use" );
-                   keyboard.getScanCodeSet();  // Get which scan code set
+                   keyboard.getScanCodeSet( );  // Get which scan code set
                    break;
       case PS2_KEY_G:
                    Serial.print( "Get current lock status = " );
-                   c = keyboard.getLock();  // Get current lock status
+                   c = keyboard.getLock( );  // Get current lock status
                    Serial.println( c, HEX );
                    break;
       case PS2_KEY_I:
                    Serial.println( "Read ID code" );
-                   keyboard.readID();  // Get which scan code set
+                   keyboard.readID( );  // Get which scan code set
                    break;
       case PS2_KEY_E:
                    Serial.println( "Echo" );
-                   keyboard.echo();  // Get which scan code set
+                   keyboard.echo( );
                    break;
       case PS2_KEY_T:
                    Serial.println( "Typematic Rate" );
@@ -213,7 +222,7 @@ if( keyboard.available() )
                    Serial.print( "No Repeat Makes for CTRL... " );
                    repeats ^= 1;
                    Serial.println( repeats );
-                   keyboard.setNoRepeat( repeats );  // Set repeat modet
+                   keyboard.setNoRepeat( repeats );  // Set repeat mode
                    break;
       }
   }

extra/PS2 Keyboard.pdf

@@ -0,0 +1,53 @@
+# PS2KeyAdvanced - Porting to new boards or Architectures
+This document assumes you have some low level understanding of your board, Arduino library structures and the compiler for your board.
+
+The majority of assists you require are in PS2KeyAdvanced.h the main header file for the library which has some architecture specific defines.
+
+-  PS2_SUPPORTED
+-  PS2_REQUIRES_PROGMEM
+-  PS2_CLEAR_PENDING_IRQ
+
+This are to cope with AVR Harvard architecture and AVR and SAM issue of not clearing past events on Interrupt pin before attachInterrupt enables interrupts
+those causing false interrupt events.
+## General Rules
+To add another board type you need to make some changes
+1.  You need to determine what the define is for your architecture, as AVR uses ARDUINO_ARCH_AVR so from verbose compiling output you need to find the part in
+compiling output for YOUR BOARD that should be **-DARDUINO_ARCH_xxxx**. Where the "xxxx" is the board architecture. You need this for making later changes.
+2.  In PS2KeyAdvanced.h you need to add a specific test for your board after the AVR and SAM checks (Note PS2_SUPPORTED **must** be included in your test otherwise a compilation error will occur.) like
+~~~
+#if defined( ARDUINO_ARCH_xxxx )
+#define PS2_SUPPORTED           1
+#define PS2_REQUIRES_PROGMEM    1
+#endif
+~~~
+3.  Change library.properties to add your architecture to the comma separated list for your architecture, normally this is the "xxxx" for ARCH_ARDUINO_xxxx
+### PS2_SUPPORTED
+This flag is set to indicate we have a supported board, this flag stops a compiler error being forced.
+
+To enable for your architecture add a line in the '#if' for your architecture as follows
+~~~
+#define PS2_SUPPORTED       1
+~~~
+### PS2_REQUIRES_PROGMEM
+This determines that to have constants in Flash memory not RAM on AVR boards the PROGMEM functions have to be used.
+
+To enable for your architecture add a line in the '#if' for your architecture as follows
+~~~
+#define PS2_REQUIRES_PROGMEM    1
+~~~
+### PS2_CLEAR_PENDING_IRQ
+When sending data to the keyboard, interrupts have to be turned off and back on again, on AVR and SAM architecture any changes on the clock pin cause extra interrupts
+when attachInterrupt is used to start bit timing interrupts again, on other architectures this does not normally happen so we need to change how interrupt events
+we see for a valid byte sending. This does not affect receiving data just the sending.
+
+This defines adds an extra bit clock event interrupt step for AVR and SAM
+
+To enable for your architecture add a line in the '#if' for your architecture as follows
+~~~
+#define PS2_CLEAR_PENDING_IRQ    1
+~~~
+## Support of changes
+If you can test **ALL** functionality working, you are welcome to do a pull request from your github fork of this library. If meets our coding 
+guidelines and you can show it is has been working it will include in next release.
+
+Please note whilst we can give assistance, we probably do not have your board or maybe not the time to incorporate full support for you.

extra/Porting.md

@@ -3,6 +3,7 @@
   Written by Paul Carpenter, PC Services <[email protected]>
   Created September 2014
   Updated January 2016
+  Updated February 2020
 
   This is for a LATIN style keyboard.
 
@@ -41,9 +42,10 @@
 
    extras folder
     codes.txt       The literals (constants) you can use to match codes returned
+    PS2 Keyboard.pdf Copy of Website explaining PS2 Protocol
     readme.txt      this file
     websites.txt    Other websites about PS2 keyboard and UTF-8 character encoding
-    Iamges          folder containg images for a single NUMLOCK keypress and what
+    Images          folder containing images for a single NUMLOCK keypress and what
                     happens on the wires.
 
    src folder
@@ -175,5 +177,5 @@ For LEDs command use the following defines added together to set them
 
 Paul Carpenter
 PC Services
-January 2016
+February 2020
 http://www.pcserviceselectronics.co.uk

extra/readme.txt

@@ -1,11 +1,11 @@
 name=PS2KeyAdvanced
-version=1.0.6
+version=1.0.7
 author=Paul Carpenter <[email protected]>
 maintainer=Paul Carpenter <[email protected]>
 sentence=PS2 keyboard FULL control and ALL keys processing, as well as LED control.
 paragraph=Provides ability to convert long key stroke code sequences to a single integer, for all keys ANY Latin keyboard, even multimedia and 24 Function key keyboards.
 category=Other
 url=https://github.com/techpaul/PS2KeyAdvanced.git
-architectures=avr,sam
+architectures=avr,sam,samd1
 includes=PS2KeyAdvanced.h