You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-27Lines changed: 55 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,39 +1,30 @@
1
1
# PS2KeyAdvanced
2
2
## Arduino PS2 Keyboard FULL keyboard protocol support and full keys to integer coding
3
-
**V1.0.8** November 2020 - Add support for STM32 from user Hiabuto-de
4
-
Tested on STM32Duino-Framework and PlatformIO on STM32F103C8T6 and an IBM Model M
5
-
6
-
V1.0.7 March 2020 - Add notes for porting to other platforms, tidy ups, add SAMD1
7
-
8
-
V1.0.6 January 2020 - Fix typos, correct keyboard reset status improve library.properties
9
-
and additional reduction for easier platform handling
10
-
11
-
V1.0.4 August 2018 - Minor reduction in available() method to remove redundant extra safety checks on buffers
12
-
13
-
V1.0.3 July 2018 Improved keywords file
14
-
15
-
First Public Release Version V1.0.2
3
+
**V1.0.9** July 2021 - Add ESP32 support from user submissions
16
4
17
5
Smaller footprint than any others found and more functionality.
18
6
19
-
For other versions that just read the keycodes for all keyboard types or allow you to get the full UTF-8 configurable for any LATIN keyboard with extra functions keys as simple codes see associated reporitories for PS2KeyAdvanced and PS2KeyMap libraries. Yes these libraries even provide codes for multimedia keys and Function keys F1 to F24 (yes that is F24).
7
+
For other versions that just read the keycodes for all keyboard types or allow you to get the full UTF-8 configurable for any LATIN keyboard with
8
+
extra functions keys as simple codes see associated repositories for PS2KeyAdvanced and PS2KeyMap libraries. Yes these libraries even provide codes
9
+
for multimedia keys and Function keys F1 to F24 (yes that is F24).
20
10
21
-
### Platforms
11
+
### Platforms known to have been tested on
22
12
23
13
- Arduino AVR - tested on Uno and Mega 2560 (Users have tested on Teensy 2.0 and Teensy++ 2.0)
24
14
- Arduino SAM - tested on DUE
25
15
- SAMD1 - Seeeduino Xiao M0+ (tested by user)
26
16
- STM32 - STM32Duino-Framework and PlatformIO on STM32F103C8T6 from user Hiabuto-de
17
+
- ESP32 - ESP32 (arduino-esp32) from users dharmik768 and n6il
27
18
28
19
See later for porting to other platforms
29
20
30
21
### Test Environment
31
22
32
-
All Arduino platforms versions of test R3 Hardware
33
-
Arduino V1.6.7 and newer
34
-
DUE Board Manager package V1.6.6 or higher
23
+
- All Arduino platforms versions of test R3 Hardware
24
+
- Arduino V1.6.7 and newer
25
+
- DUE Board Manager package V1.6.6 or higher
35
26
36
-
## Important Hardware Notes
27
+
###Important Hardware Notes
37
28
38
29
1. Make sure you have data and clock wires connected correctly. Clock wire MUST be connected to an interrupt pin.
39
30
@@ -50,14 +41,21 @@ See later for porting to other platforms
50
41
- Teensy++ 1.0: 0, 1, 2, 3, 18, 19, 36, 37
51
42
- Sanguino: 2, 10, 11
52
43
53
-
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.
44
+
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
45
+
not only operate at 5V but the two wire communications are pulled up by a resistor to 5V at the keyboard end.
46
+
3. USB keyboards through PS2 adapter draw **LOTS** of current and can cause processor and/or keyboard to RESET if not EXTERNALLY POWERED. It is best
47
+
to work with 'native' PS2 keyboards.
54
48
55
-
### Introduction
56
-
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..
49
+
## Introduction
50
+
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
51
+
PS2 Keyboard libraries. This is the second which fully supports the PS2 Keyboard Protocol, even allowing you control of keyboard LEDs (some have 4
52
+
LEDs) and changing settings..
57
53
58
54
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.
59
55
60
-
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.
56
+
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),
57
+
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
58
+
sent from a keyboard into its small buffer and read out the codes with simple methods.
61
59
62
60
Returns any keypress as 16 bit integer, which includes a coded value for the key along with status for
63
61
@@ -85,15 +83,45 @@ Fully featured PS2 keyboard library to provide
85
83
86
84
### Installation
87
85
Performed by standard zip file library inclusion into Arduino IDE
86
+
87
+
### IDE Configuration
88
+
It is recommended that users compile with ALL errors and warnings displayed in Arduino IDE, to perform this select
89
+
menu functions
90
+
91
+
File --> Preferences
92
+
93
+
- On "Show verbose output during" Select "Compiling"
94
+
- On next line "Compiler Warnings" select "All"
95
+
- Select "OK"
96
+
- Restart IDE and test compile an example.
97
+
88
98
### Examples
89
-
This library has THREE examples, from simplest to most complec -
99
+
This library has THREE examples, from simplest to most complex -
90
100
91
101
- SimpleTest that uses the serial port to output the converted codes received on every keystroke and auto-repeat.
92
-
- 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).
93
-
- 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
102
+
- 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
# PS2KeyAdvanced - Porting to new boards or Architectures
1
+
# PS2KeyAdvanced - Porting to New Boards or Architectures
2
2
This document assumes you have some low level understanding of your board, Arduino library structures and the compiler for your board.
3
3
4
4
The majority of assists you require are in PS2KeyAdvanced.h the main header file for the library which has some architecture specific defines.
5
5
6
+
When a valid supported architecture is supported this flag is set. Without this set for a **VALID** architecture that is supported
7
+
a compiler warning or hard error is reported on compiling.
8
+
6
9
- PS2_SUPPORTED
10
+
11
+
These are to cope with AVR Harvard architecture, AVR and SAM (many but not all architectures) issue of *not* clearing past events on Interrupt pin
12
+
before attachInterrupt enables interrupts those causing false interrupt events.
13
+
7
14
- PS2_REQUIRES_PROGMEM
8
15
- PS2_CLEAR_PENDING_IRQ
9
16
10
-
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
11
-
those causing false interrupt events.
17
+
The following is to cope with architectures that use CHANGE interrupt even when asking for FALLING.
18
+
- PS2_ONLY_CHANGE_IRQ
19
+
12
20
## General Rules
13
21
To add another board type you need to make some changes
14
-
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
15
-
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.
16
-
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
22
+
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
23
+
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
24
+
making later changes.
25
+
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
26
+
test otherwise a compilation error will occur.) like
17
27
~~~
18
28
#if defined( ARDUINO_ARCH_xxxx )
19
29
#define PS2_SUPPORTED 1
20
30
#define PS2_REQUIRES_PROGMEM 1
21
31
#endif
22
32
~~~
23
33
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
34
+
35
+
If your architecture needs an **EXTRA** flag then it must have a name describing the functionality the flag enables
36
+
**NOT** the board or architecture name. this means it is easier to be readable to others and may also be needed for other
37
+
other boards or architectures.
24
38
### PS2_SUPPORTED
25
39
This flag is set to indicate we have a supported board, this flag stops a compiler error being forced.
26
40
@@ -36,18 +50,30 @@ To enable for your architecture add a line in the '#if' for your architecture as
36
50
#define PS2_REQUIRES_PROGMEM 1
37
51
~~~
38
52
### PS2_CLEAR_PENDING_IRQ
39
-
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
40
-
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
41
-
we see for a valid byte sending. This does not affect receiving data just the sending.
53
+
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
54
+
cause extra interrupts when attachInterrupt is used to start bit timing interrupts again, on other architectures this does not normally happen so we
55
+
need to change how many interrupt events we see for a valid byte sending. This does not affect receiving data just the sending.
42
56
43
57
This defines adds an extra bit clock event interrupt step for AVR and SAM
44
58
45
59
To enable for your architecture add a line in the '#if' for your architecture as follows
46
60
~~~
47
61
#define PS2_CLEAR_PENDING_IRQ 1
48
62
~~~
63
+
### PS2_ONLY_CHANGE_IRQ
64
+
This came about when the processor or the board package does not support all types of interrupt, the library uses
65
+
FALLING (falling edge when signal goes from high to low), some processors or board packages do not implement this
66
+
and use CHANGE interrupt (both edges) even if you ask for one edge.
67
+
68
+
To enable for your architecture add a line in the '#if' for your architecture as follows
69
+
~~~
70
+
#define PS2_ONLY_CHANGE_IRQ 1
71
+
~~~
72
+
This was first required for ESP32, which has a SILICON (hardware) MCU problem and workarounds **SHOULD** have been incorporated into arduino-esp32
73
+
https://github.com/espressif/arduino-esp32 The issue there are **SPURIOUS** extra interrupts.
49
74
## Support of changes
50
-
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
75
+
If you can test **ALL** functionality working, you are welcome to do a pull request from your github fork of this library. If this meets our coding
51
76
guidelines and you can show it is has been working it will include in next release.
52
77
53
-
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.
78
+
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. of course we
79
+
can always accept standard commercial daily rates to this for your, if you are made of money and willing for result to be publicly available for free.
sentence=PS2 keyboard FULL control and ALL keys processing, as well as LED control.
6
-
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.
6
+
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. Architectures AVR, SAM (Due), SAMD1, STM32
0 commit comments