Difference between revisions of "Example getkey"

From wiki.emacinc.com
Jump to: navigation, search
(→‎Usage Example. Mapping the Keypad to a Matrix File)
 
(133 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
{{todo|InProgress(11.14.13-11:41->JG+);(11.14.13-15:30->MD-);(11.19.13-09:13->JG+)|Jgreene|project=oe 4,oe 5,jg,md,Review}}
+
{{todo|SEOKWREV (11.14.13-11:41->JG+);(11.14.13-15:30->MD-);(11.21.13-14:06->JG+);(11.21.13-16:15->MD-);(12.03.13-14:21->JG+);(01.04.14-17:01->JG+);(01.03.14-17:15->MD+);(01.03.14-17:35->KY+);(04.03.14-16:20->BS+)|Jgreene|project=oe 4,oe 5,jg,md,SEOKWREV,ky,bs}}
−
This procedure provides an overview of how to open, build and run the ''getkey'' C example project using the Eclipse IDE.
+
 
 +
{{#seo:
 +
|title=Example getkey
 +
|titlemode=append
 +
|keywords=Example getkey,EMAC SOM-150ES,Using getkey,E020-21 Membrane hex style keypad
 +
|description=This is a guide to the <code>getkey</code> C example project included in the EMAC OE SDK.
 +
}}
 +
This is a guide to the <code>getkey</code> C example project included in the EMAC OE SDK.
 +
 
 +
The <code>getkey</code> example C project demonstrates how to use a keypad with a SoM150ES carrier board. It provides examples of how to specify, inspect and test associations between character-data and keypad-keys. It demonstrates how to turn key-presses into character-data using the same techniques as the big keyboard on your PC. It's also a good introduction to the mysteries of matrix encoding (see [http://wikidev.emacinc.com/wiki/Example_getkey#A_Note_on_Matrix_Encoding A Note on Matrix Encoding, below]).
 +
 
 +
The <code>getkey</code> C example project creates one executable: <code>getkey</code>.
  
 
== Opening, Building and Uploading the Project Files ==
 
== Opening, Building and Uploading the Project Files ==
  
−
<big>'''1. Open the ''C/C++'' editing perspective.'''</big>
+
For information on opening the project from within Eclipse, please see [[Importing the EMAC OE SDK Projects with Eclipse]].  Then, follow [[Using the EMAC OE SDK Projects with Eclipse]] for information on how to build, upload and execute the example.
 +
 
 +
Alternatively, the <code>Makefile</code> can be used with the <code>make</code> command from the commandline to build and upload the example.  For information on this method, please see [[Using EMAC OE SDK Example Projects]].
 +
 
 +
====EMAC SDK 5.X====
 +
 
 +
For information on opening the project from within QtCreator, please see [[Getting_Started_With_Qt_Creator#Adding_Source_Files | QtCreator: Adding Source Files]].  Then, follow [[Getting Started With Qt Creator]] for information on how to build, upload and execute the example.
 +
 
 +
Alternatively, the <code>CMakefile.txt</code> can be used with the <code>cmake</code> command from the commandline to build and upload the example.  For information on this method, please see [[Getting_Started_with_the_EMAC_OE_SDK#Target_Machine_Compiling | Getting Started with the EMAC OE SDK]].
 +
 
 +
Code can be found at http://git.emacinc.com/OE/example-projects
 +
==Usage and Behavior==
 +
 
 +
===Hardware Requirements===
 +
 
 +
To use the '''getkey''' program requires the following hardware.
 +
 
 +
* A [http://www.emacinc.com/som/som150es.htm SOM-150ES carrier board] (Available from EMAC).<br />
 +
* A compatible SoM for that carrier board ([http://www.emacinc.com/products/system_on_module/SoM-9260M SOM-9260M], [http://www.emacinc.com/som/som9G20.htm SOM-9G20M] and [http://www.emacinc.com/som/som9x25.htm SOM-9X25] are all compatible and available from EMAC).<br />
 +
* A compatible keypad ([http://www.emacinc.com/sbc_microcontroller_addons.htm Available from EMAC], refer to item# E20-21 or E020-25. [https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=0CCsQFjAA&url=http%3A%2F%2Fwww.in2tec.com%2Flib%2Fdownloadfile.php%3Ffilename%3D4000_series_keypads_datasheet.pdf%26loc%3Ddocuments%2F%26ct%3Dpdf&ei=Wf-MUrGxO-nEyQGggoGgCg&usg=AFQjCNEQxIaiH6-gx6uTq4O66o1YVDunZw&bvm=bv.56643336,d.aWc Datasheet]).
 +
 
 +
[[File:Som150 with keypad.JPG | 500px ]]<br />
 +
SOM-150ES carrier board with keypad
 +
 
 +
===Plugging the Keypad into the SOM-150ES Carrier Board===
 +
 
 +
Plug the keypad into the HDR5 KEYPAD header of the SOM-150ES Carrier Board.<br />
 +
[[File:Example getkey howtopluginthekeypad 0.png|500px]]
 +
 
 +
Ensure that '''pin 0''' of the keypad's ribbon cable is lined up with '''pin 2''' on the header.<br />
 +
[[File:Example getkey howtopluginthekeypad 1.png|500px]]
 +
 
 +
===The Keypad Matrix File===
 +
 
 +
The keypad matrix file specifies associations between keypad-keys and characters. For each key in the keypad's grid of keys we specify a character in a grid of characters.
 +
 
 +
&nbsp; &nbsp; &nbsp; &nbsp; [[File:Example_getkey_minimalkeypad.png|200px]] &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; [[File: Example_getkey_matrixfile.png|150px]]
  
−
stub
+
In this example we see an E020-21 keypad on the left and an example keypad matrix file (<code>Key-E020-21</code>, included in the project) opened in a text editor on the right. The character matrix may be freely edited to suit.
  
−
<big>'''2. Open the ''getkey'' project files.'''</big>
+
====A Note on Matrix Encoding====
  
−
stub
+
Matrix Encoding is a technique for translating individual xy locations on a 2D matrix into unique integer values. Here we see locations in a 4x4 matrix being translated into an 8-bit value. Pins 0, 1, 2, 3 handle the key y coordinate; pins 4, 5, 6, 7 handle the x coordinate. Key '''A''' is at (7,0); '''B''':(6,0); '''K''':(5,2); Etc.
  
−
<big>'''3. Build the ''getkey'' project.'''</big>
+
&nbsp; &nbsp; &nbsp; &nbsp; [[File:Matrix encoding.png]]
  
−
stub
+
Thus, when a key is pressed, we get a corresponding integer value on the header.<br />
 +
For example: Pressing the '''F''' key sets the values on pins '''1''' and '''6''' to 1. This gives us a binary value of 01000010. Integer value: 66 . So when the value at the header equals 66, we know that the '''F''' key was pressed.<br />
 +
'''Note:''' This is an abstract, general example of a keypad using matrix encoding. Your keypad will probably have different characters on it's keys and output slightly different values.
  
−
<big>'''4. Upload the ''getkey'' binary to the target machine.'''</big>
+
===Using getkey===
  
−
stub
+
The '''getkey''' program is controlled from the console via command line parameters. You can specify the keypad device node, specify the keypad matrix file (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above), display the current matrix in the console and test individual character-key associations.
  
−
== Description, Usage and Expected Behaviour ==
+
<code>./getkey [-d device -b -g -s file]</code>
  
−
This is an example program for mapping keypad input to a character matrix using the keypad interface on the SOM-150ES.  
+
;-d:Specify the keypad device node. The default is <code>/dev/keypad</code>
 +
;-b:Test an individual key-character association (via "read blocking"). The program will sleep until a key on the keypad is pressed, then output that key's character to the console.
 +
;-g:Outputs the current keypad matrix (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above) to the console.
 +
;-s:Specify the keypad matrix file. (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above). If a keypad matrix file is not specified then the character associated with the last keypad key pressed is returned.
  
−
''To use this program you will need the appropriate hardware:''<br />
+
'''Note on parameter order:''' Parameters are evaluated in order. If blocking ('''b''') or device specifications ('''d''') are used, they must be declared before the matrix arguments on the command line.
−
A '''SOM-150ES carrier board'''.<br />
 
−
A compatible '''SoM''' for that carrier board ('''SOM-9260M''', '''SOM-9620M''' and '''SOM-9X25''' are all compatible and available from EMAC).<br />
 
−
A compatible '''keypad''' (Available from EMAC, item# E202-21).  
 
−
 
−
'''Usage for getkey'''
 
  
−
    <code>getkey [-d device -b -g -s file]</code>
+
===Usage Example. Mapping a Keypad Device Node to a Keypad Matrix File===
−
{| class="wikitable"
 
−
|-
 
−
| '''d''' || Specifies the device node. The default is <code>/dev/keypad</code>
 
−
|-
 
−
| '''b''' || Activates read blocking. The program will sleep until a key on the keypad is pressed.
 
−
|-
 
−
| '''g''' || Returns the current keypad matrix.
 
−
|-
 
−
| '''s''' || Sets the keypad matrix to that of the specified matrix file. (See project for example file <code>Key-E020-21</code>). If a matrix operation is not specified then the last key pressed is returned.
 
−
|}
 
  
−
'''Note''' Arguments are evaluated in order. If blocking or device specifications are used, they must be declared before the matrix arguments on the command line.
+
<code>./getkey -d /dev/keypad0 -s /path/to/this/file/Key-E020-21</code>
  
−
===Usage Example. Mapping the Keypad to a Matrix File===
+
The program will map the keypad at the device node <code>/dev/keypad0</code> to the matrix file <code>Key-E020-21</code>. This associates each character in the grid of characters in the matrix file (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above) with a key in the grid of keys on the keypad.
  
−
    <code>./getkey -d /dev/keypad0 -s Key-E020-21</code>
+
===Usage Example: Displaying the Character Presently Associated With a Key on the Keypad===
  
−
The program will map the keypad at <code>/dev/keypad0</code> to the matrix file <code>Key-E020-21</code>.
+
<code>./getkey -d /dev/keypad0 -b</code>
  
−
===Usage Example. Displaying the Matrix Presently Associated with the Keypad===
+
The program will wait until a key is pressed on the keypad. When a key is pressed it will display the character associated with that pressed key, as specified in the keypad matrix file (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above).
  
−
    <code>./getkey -d /dev/keypad0 -g</code>
+
For example:
 +
<syntaxhighlight lang="console">
 +
root@som9g20:/tmp# ./getkey -d /dev/keypad0 -b
 +
5
 +
root@som9g20:/tmp#
 +
</syntaxhighlight>
 +
In this case, the '''5''' key on the keypad was pressed.
  
−
The program will display the matrix presently associated with the keypad at <code>/dev/keypad0''</code>.
+
===Usage Example. Displaying the Character Matrix Presently Associated with the Keypad===
  
−
'''example output'''
+
<code>./getkey -d /dev/keypad0 -g</code>
  
−
===Usage Example. Displaying the Character Presently Mapped to a Key on the Keypad===
+
The program will display the character matrix (see notes on the [http://wikidev.emacinc.com/wiki/Example_getkey#The_Keypad_Matrix_File keypad matrix file], above) presently associated with the keypad at <code>/dev/keypad0''</code>.
  
−
    <code>./getkey -d /dev/keypad0 -b</code>
+
<syntaxhighlight lang="console">
 +
root@som9g20:/tmp# ./getkey -d /dev/keypad0 -g
 +
1 2 3 C 
 +
4 5 6 D 
 +
7 8 9 E 
 +
A 0 B F 
 +
root@som9g20:/tmp#
 +
</syntaxhighlight>
 +
The character matrix displayed here is that of the <code>Key-E020-21</code> file.
  
−
The program will wait until a key is pressed on the keypad. When a key is pressed it will display the corresponding character mapped to that pressed key, as specified in the matrix file.
+
==Summary==
  
−
'''example output'''
+
The <code>getkey</code> example C project demonstrates how to use a keypad with a SoM150ES carrier board.

Latest revision as of 13:20, 30 November 2022

TODO: {{#todo:SEOKWREV (11.14.13-11:41->JG+);(11.14.13-15:30->MD-);(11.21.13-14:06->JG+);(11.21.13-16:15->MD-);(12.03.13-14:21->JG+);(01.04.14-17:01->JG+);(01.03.14-17:15->MD+);(01.03.14-17:35->KY+);(04.03.14-16:20->BS+)|Jgreene|oe 4,oe 5,jg,md,SEOKWREV,ky,bs}}

This is a guide to the getkey C example project included in the EMAC OE SDK.

The getkey example C project demonstrates how to use a keypad with a SoM150ES carrier board. It provides examples of how to specify, inspect and test associations between character-data and keypad-keys. It demonstrates how to turn key-presses into character-data using the same techniques as the big keyboard on your PC. It's also a good introduction to the mysteries of matrix encoding (see A Note on Matrix Encoding, below).

The getkey C example project creates one executable: getkey.

Opening, Building and Uploading the Project Files

For information on opening the project from within Eclipse, please see Importing the EMAC OE SDK Projects with Eclipse. Then, follow Using the EMAC OE SDK Projects with Eclipse for information on how to build, upload and execute the example.

Alternatively, the Makefile can be used with the make command from the commandline to build and upload the example. For information on this method, please see Using EMAC OE SDK Example Projects.

EMAC SDK 5.X

For information on opening the project from within QtCreator, please see QtCreator: Adding Source Files. Then, follow Getting Started With Qt Creator for information on how to build, upload and execute the example.

Alternatively, the CMakefile.txt can be used with the cmake command from the commandline to build and upload the example. For information on this method, please see Getting Started with the EMAC OE SDK.

Code can be found at http://git.emacinc.com/OE/example-projects

Usage and Behavior

Hardware Requirements

To use the getkey program requires the following hardware.

Som150 with keypad.JPG
SOM-150ES carrier board with keypad

Plugging the Keypad into the SOM-150ES Carrier Board

Plug the keypad into the HDR5 KEYPAD header of the SOM-150ES Carrier Board.
Example getkey howtopluginthekeypad 0.png

Ensure that pin 0 of the keypad's ribbon cable is lined up with pin 2 on the header.
Example getkey howtopluginthekeypad 1.png

The Keypad Matrix File

The keypad matrix file specifies associations between keypad-keys and characters. For each key in the keypad's grid of keys we specify a character in a grid of characters.

        Example getkey minimalkeypad.png           Example getkey matrixfile.png

In this example we see an E020-21 keypad on the left and an example keypad matrix file (Key-E020-21, included in the project) opened in a text editor on the right. The character matrix may be freely edited to suit.

A Note on Matrix Encoding

Matrix Encoding is a technique for translating individual xy locations on a 2D matrix into unique integer values. Here we see locations in a 4x4 matrix being translated into an 8-bit value. Pins 0, 1, 2, 3 handle the key y coordinate; pins 4, 5, 6, 7 handle the x coordinate. Key A is at (7,0); B:(6,0); K:(5,2); Etc.

        Matrix encoding.png

Thus, when a key is pressed, we get a corresponding integer value on the header.
For example: Pressing the F key sets the values on pins 1 and 6 to 1. This gives us a binary value of 01000010. Integer value: 66 . So when the value at the header equals 66, we know that the F key was pressed.
Note: This is an abstract, general example of a keypad using matrix encoding. Your keypad will probably have different characters on it's keys and output slightly different values.

Using getkey

The getkey program is controlled from the console via command line parameters. You can specify the keypad device node, specify the keypad matrix file (see notes on the keypad matrix file, above), display the current matrix in the console and test individual character-key associations. 

./getkey [-d device -b -g -s file]
-d
Specify the keypad device node. The default is /dev/keypad
-b
Test an individual key-character association (via "read blocking"). The program will sleep until a key on the keypad is pressed, then output that key's character to the console.
-g
Outputs the current keypad matrix (see notes on the keypad matrix file, above) to the console.
-s
Specify the keypad matrix file. (see notes on the keypad matrix file, above). If a keypad matrix file is not specified then the character associated with the last keypad key pressed is returned.

Note on parameter order: Parameters are evaluated in order. If blocking (b) or device specifications (d) are used, they must be declared before the matrix arguments on the command line.

Usage Example. Mapping a Keypad Device Node to a Keypad Matrix File

./getkey -d /dev/keypad0 -s /path/to/this/file/Key-E020-21

The program will map the keypad at the device node /dev/keypad0 to the matrix file Key-E020-21. This associates each character in the grid of characters in the matrix file (see notes on the keypad matrix file, above) with a key in the grid of keys on the keypad.

Usage Example: Displaying the Character Presently Associated With a Key on the Keypad

./getkey -d /dev/keypad0 -b

The program will wait until a key is pressed on the keypad. When a key is pressed it will display the character associated with that pressed key, as specified in the keypad matrix file (see notes on the keypad matrix file, above).

For example: 

root@som9g20:/tmp# ./getkey -d /dev/keypad0 -b
5
root@som9g20:/tmp#

In this case, the 5 key on the keypad was pressed.

Usage Example. Displaying the Character Matrix Presently Associated with the Keypad

./getkey -d /dev/keypad0 -g

The program will display the character matrix (see notes on the keypad matrix file, above) presently associated with the keypad at /dev/keypad0. 

root@som9g20:/tmp# ./getkey -d /dev/keypad0 -g
1 2 3 C   
4 5 6 D   
7 8 9 E   
A 0 B F   
root@som9g20:/tmp#

The character matrix displayed here is that of the Key-E020-21 file.

Summary

The getkey example C project demonstrates how to use a keypad with a SoM150ES carrier board.

Retrieved from "https://wiki.emacinc.com/index.php?title=Example_getkey&oldid=15100"