The PS2 Keyboard controller class. More...

#include <keyboard.h>

Inheritance diagram for fabgl::KeyboardClass:

Collaboration diagram for fabgl::KeyboardClass:

Public Member Functions
void	begin (gpio_num_t clkGPIO, gpio_num_t dataGPIO, bool generateVirtualKeys=true, bool createVKQueue=true)
	Initializes KeyboardClass specifying CLOCK and DATA GPIOs. More...

void	begin (bool generateVirtualKeys, bool createVKQueue, int PS2Port)
	Initializes KeyboardClass without initializing the PS/2 controller. More...

void	emptyVirtualKeyQueue ()
	Empties the virtual keys queue. More...

KeyboardLayout const *	getLayout ()
	Gets current keyboard layout. More...

void	getLEDs (bool numLock, bool capsLock, bool *scrollLock)
	Gets keyboard LEDs status. More...

int	getNextScancode (int timeOutMS=-1, bool requestResendOnTimeOut=false)
	Gets a scancode from the queue. More...

VirtualKey	getNextVirtualKey (bool *keyDown=nullptr, int timeOutMS=-1)
	Gets a virtual key from the queue. More...

PS2Device	identify ()
	Identifies the device attached to the PS2 port. More...

bool	isKeyboardAvailable ()
	Checks if keyboard has been detected and correctly initialized. More...

bool	isVKDown (VirtualKey virtualKey)
	Gets the virtual keys status. More...

bool	lock (int timeOutMS)
	Gets exclusive access to the device. More...

bool	reset ()
	Sends a Reset command to the keyboard. More...

int	scancodeAvailable ()
	Gets the number of scancodes available in the queue. More...

void	setLayout (KeyboardLayout const *layout)
	Sets keyboard layout. More...

bool	setLEDs (bool numLock, bool capsLock, bool scrollLock)
	Sets keyboard LEDs status. More...

bool	setTypematicRateAndDelay (int repeatRateMS, int repeatDelayMS)
	Sets typematic rate and delay. More...

void	setUIApp (uiApp *app)
	Sets current UI app. More...

void	suspendVirtualKeyGeneration (bool value)
	Suspends or resume the virtual key generation task. More...

void	unlock ()
	Releases device from exclusive access. More...

int	virtualKeyAvailable ()
	Gets the number of virtual keys available in the queue. More...

int	virtualKeyToASCII (VirtualKey virtualKey)
	Converts virtual key to ASCII. More...

Detailed Description

The PS2 Keyboard controller class.

KeyboardClass connects to one port of the PS2 Controller class (fabgl::PS2ControllerClass) and provides the logic that converts scancodes to virtual keys or ASCII (and ANSI) codes.
It optionally creates a task that waits for scan codes from the PS2 device and puts virtual keys in a queue.
The PS2 controller uses ULP coprocessor and RTC slow memory to communicate with the PS2 device.

It is possible to specify an international keyboard layout. The default is US-layout.
There are three predefined kayboard layouts: US (USA), UK (United Kingdom), DE (German) and IT (Italian). Other layout can be added inheriting from US or from any other layout.

Applications do not need to create an instance of KeyboardClass because an instance named Keyboard is created automatically.

Example:

// Setup pins GPIO33 for CLK and GPIO32 for DATA
Keyboard.begin(GPIO_NUM_33, GPIO_NUM_32);  // clk, dat

// Prints name of received virtual keys
while (true)
  Serial.printf("VirtualKey = %s\n", Keyboard.virtualKeyToString(Keyboard.getNextVirtualKey()));

Member Function Documentation

◆ begin() [1/2]

void fabgl::KeyboardClass::begin	(	gpio_num_t	clkGPIO,
		gpio_num_t	dataGPIO,
		bool	generateVirtualKeys = `true`,
		bool	createVKQueue = `true`
	)

Initializes KeyboardClass specifying CLOCK and DATA GPIOs.

A reset command (KeyboardClass.reset() method) is automatically sent to the keyboard.
This method also initializes the PS2ControllerClass to use port 0 only.

Parameters

clkGPIO	The GPIO number of Clock line
dataGPIO	The GPIO number of Data line
generateVirtualKeys	If true creates a task which consumes scancodes to produce virtual keys, so you can call KeyboardClass.isVKDown().
createVKQueue	If true creates a task which consunes scancodes and produces virtual keys and put them in a queue, so you can call KeyboardClass.isVKDown(), KeyboardClass.virtualKeyAvailable() and KeyboardClass.getNextVirtualKey().

Example:

// Setup pins GPIO33 for CLK and GPIO32 for DATA
Keyboard.begin(GPIO_NUM_33, GPIO_NUM_32);  // clk, dat

◆ begin() [2/2]

void fabgl::KeyboardClass::begin	(	bool	generateVirtualKeys,
		bool	createVKQueue,
		int	PS2Port
	)

Initializes KeyboardClass without initializing the PS/2 controller.

A reset command (KeyboardClass.reset() method) is automatically sent to the keyboard.
This method does not initialize the PS2ControllerClass.

Parameters

generateVirtualKeys	If true creates a task which consumes scancodes and produces virtual keys, so you can call KeyboardClass.isVKDown().
createVKQueue	If true creates a task which consunes scancodes to produce virtual keys and put them in a queue, so you can call KeyboardClass.isVKDown(), KeyboardClass.virtualKeyAvailable() and KeyboardClass.getNextVirtualKey().
PS2Port	The PS/2 port to use (0 or 1).

Example:

// Setup pins GPIO33 for CLK and GPIO32 for DATA on port 0
PS2Controller.begin(GPIO_NUM_33, GPIO_NUM_32); // clk, dat
Keyboard.begin(true, true, 0); // port 0

◆ emptyVirtualKeyQueue()

void fabgl::KeyboardClass::emptyVirtualKeyQueue ( )

Empties the virtual keys queue.

Examples:: VIC20/VIC20.ino.

◆ getLayout()

KeyboardLayout const* fabgl::KeyboardClass::getLayout ( )

inline

Gets current keyboard layout.

Returns: The default or last set keyboard layout.

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ getLEDs()

void fabgl::KeyboardClass::getLEDs	(	bool *	numLock,
		bool *	capsLock,
		bool *	scrollLock
	)

Gets keyboard LEDs status.

Use this method to know the current status of NUMLOCK, CAPSLOCK and SCROLLLOCK LEDs.

Parameters

numLock	When true the NUMLOCK LED is switched on.
capsLock	When true the CAPSLOCK LED is switched on.
scrollLock	When true the SCROLLLOCK LED is switched on.

◆ getNextScancode()

int fabgl::KeyboardClass::getNextScancode	(	int	timeOutMS = `-1`,
		bool	requestResendOnTimeOut = `false`
	)

Gets a scancode from the queue.

Scancodes are always generated but they can be consumed by the scancode-to-virtualkeys task. So, in order to use this method KeyboardClass.begin() method should be called with generateVirtualKeys = false and createVKQueue = false.
Alternatively it is also possible to suspend the conversion task calling KeyboardClass.suspendVirtualKeyGeneration() method.

Parameters

timeOutMS	Timeout in milliseconds. -1 means no timeout (infinite time).
requestResendOnTimeOut	If true and timeout has expired then asks the keyboard to resend the scancode.

Returns: The first scancode of the queue (-1 if no data is available in the timeout period).

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ getNextVirtualKey()

VirtualKey fabgl::KeyboardClass::getNextVirtualKey	(	bool *	keyDown = `nullptr`,
		int	timeOutMS = `-1`
	)

Gets a virtual key from the queue.

Virtual keys are generated from scancodes only if generateVirtualKeys parameter is true (default) and createVKQueue parameter is true (default) of KeyboardClass.begin() method.

Parameters

keyDown	A pointer to boolean variable which will contain if the virtual key is depressed (true) or released (false).
timeOutMS	Timeout in milliseconds. -1 means no timeout (infinite time).

Returns: The first virtual key of the queue (VK_NONE if no data is available in the timeout period).

Examples:: KeyboardStudio/KeyboardStudio.ino, and VIC20/VIC20.ino.

◆ identify()

PS2Device fabgl::PS2DeviceClass::identify ( )

inlineinherited

Identifies the device attached to the PS2 port.

Returns: The identification ID sent by keyboard.

Examples:: KeyboardStudio/KeyboardStudio.ino, and MouseStudio/MouseStudio.ino.

◆ isKeyboardAvailable()

bool fabgl::KeyboardClass::isKeyboardAvailable ( )

inline

Checks if keyboard has been detected and correctly initialized.

isKeyboardAvailable() returns a valid value only after KeyboardClass.begin() or KeyboardClass.reset() has been called.

Returns: True if the keyboard is correctly initialized.

Examples:: AnsiTerminal/AnsiTerminal.ino, KeyboardStudio/KeyboardStudio.ino, LoopbackTerminal/LoopbackTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ isVKDown()

bool fabgl::KeyboardClass::isVKDown ( VirtualKey virtualKey )

Gets the virtual keys status.

This method allows to know the status of each virtual key (Down or Up).
Virtual keys are generated from scancodes only if generateVirtualKeys parameter of KeyboardClass.begin() method is true (default).

Parameters

virtualKey The Virtual Key to test.

Returns: True if the specified virtual key is down.

Examples:: SpaceInvaders/SpaceInvaders.ino.

◆ lock()

bool fabgl::PS2DeviceClass::lock ( int timeOutMS )

inherited

Gets exclusive access to the device.

Parameters

timeOutMS Timeout in milliseconds to wait before fail.

Returns: True if the device has been locked.

◆ reset()

bool fabgl::KeyboardClass::reset ( )

Sends a Reset command to the keyboard.

Returns: True if the keyboard is correctly initialized.

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ scancodeAvailable()

int fabgl::KeyboardClass::scancodeAvailable ( )

Gets the number of scancodes available in the queue.

Scancodes are always generated but they can be consumed by the scancode-to-virtualkeys task. So, in order to use this method KeyboardClass.begin() method should be called with generateVirtualKeys = false and createVKQueue = false.
Alternatively it is also possible to suspend the conversion task calling KeyboardClass.suspendVirtualKeyGeneration() method.

Returns: The number of scancodes available to read.

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ setLayout()

void fabgl::KeyboardClass::setLayout ( KeyboardLayout const * layout )

Sets keyboard layout.

It is possible to specify an international keyboard layout. The default is US-layout.
There are three predefined kayboard layouts: US (USA), UK (United Kingdom), DE (German) and IT (Italian). Other layout can be added inheriting from US or from any other layout.

Parameters

layout A pointer to the layout structure.

Example:

// Set German layout
setLayout(&fabgl::GermanLayout);

Examples:: Altair8800/Altair8800.ino, KeyboardStudio/KeyboardStudio.ino, and VIC20/VIC20.ino.

◆ setLEDs()

bool fabgl::KeyboardClass::setLEDs	(	bool	numLock,
		bool	capsLock,
		bool	scrollLock
	)

inline

Sets keyboard LEDs status.

Use this method to switch-on or off the NUMLOCK, CAPSLOCK and SCROLLLOCK LEDs.

Parameters

numLock	When true the NUMLOCK LED is switched on.
capsLock	When true the CAPSLOCK LED is switched on.
scrollLock	When true the SCROLLLOCK LED is switched on.

Returns: True if command has been successfully delivered to the keyboard.

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ setTypematicRateAndDelay()

bool fabgl::KeyboardClass::setTypematicRateAndDelay	(	int	repeatRateMS,
		int	repeatDelayMS
	)

inline

Sets typematic rate and delay.

If the key is kept pressed down, after repeatDelayMS keyboard starts periodically sending codes with frequency repeatRateMS.

Parameters

repeatRateMS	Repeat rate in milliseconds (in range 33 ms ... 500 ms).
repeatDelayMS	Repeat delay in milliseconds (in range 250 ms ... 1000 ms, steps of 250 ms).

Returns: True if command has been successfully delivered to the keyboard.

◆ setUIApp()

void fabgl::KeyboardClass::setUIApp ( uiApp * app )

inline

Sets current UI app.

To use this generateVirtualKeys must be true in begin().

Parameters

app	The UI app where to send keyboard events

◆ suspendVirtualKeyGeneration()

void fabgl::KeyboardClass::suspendVirtualKeyGeneration ( bool value )

Suspends or resume the virtual key generation task.

Use this method to temporarily suspend the scancode to virtual key conversion task. This is useful when scancode are necessary for a limited time.

Parameters

value If true conversion task is suspended. If false conversion task is resumed.

Examples:: KeyboardStudio/KeyboardStudio.ino.

◆ unlock()

void fabgl::PS2DeviceClass::unlock ( )

inherited

Releases device from exclusive access.

◆ virtualKeyAvailable()

int fabgl::KeyboardClass::virtualKeyAvailable ( )

Gets the number of virtual keys available in the queue.

Virtual keys are generated from scancodes only if generateVirtualKeys parameter is true (default) and createVKQueue parameter is true (default) of KeyboardClass.begin() method.

Returns: The number of virtual keys available to read.

Examples:: KeyboardStudio/KeyboardStudio.ino, and VIC20/VIC20.ino.

◆ virtualKeyToASCII()

int fabgl::KeyboardClass::virtualKeyToASCII ( VirtualKey virtualKey )

Converts virtual key to ASCII.

This method converts the specified virtual key to ASCII, if possible.
For example VK_A is converted to 'A' (ASCII 0x41), CTRL + VK_SPACE produces ASCII NUL (0x00), CTRL + letter produces ASCII control codes from SOH (0x01) to SUB (0x1A), CTRL + VK_BACKSLASH produces ASCII FS (0x1C), CTRL + VK_QUESTION produces ASCII US (0x1F), CTRL + VK_LEFTBRACKET produces ASCII ESC (0x1B), CTRL + VK_RIGHTBRACKET produces ASCII GS (0x1D), CTRL + VK_TILDE produces ASCII RS (0x1E) and VK_SCROLLLOCK produces XON or XOFF.

Parameters

virtualKey The virtual key to convert.

Returns: The ASCII code of virtual key or -1 if virtual key cannot be translated to ASCII.

Examples:: KeyboardStudio/KeyboardStudio.ino.

The documentation for this class was generated from the following files:

keyboard.h
keyboard.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ emptyVirtualKeyQueue()

◆ getLayout()

◆ getLEDs()

◆ getNextScancode()

◆ getNextVirtualKey()

◆ identify()

◆ isKeyboardAvailable()

◆ isVKDown()

◆ lock()

◆ reset()

◆ scancodeAvailable()

◆ setLayout()

◆ setLEDs()

◆ setTypematicRateAndDelay()

◆ setUIApp()

◆ suspendVirtualKeyGeneration()

◆ unlock()

◆ virtualKeyAvailable()

◆ virtualKeyToASCII()