OpenAG5

Open firmware for the AlphaGrip5 keyboard

Suraj N. Kurapati

27 December 2007

Document

Chapter 1
Introduction

The OpenAG5 project aims to provide open-source firmware and reverse-engineered device documentation for the revolutionary AlphaGrip5 (AG5) keyboard.

Open firmware allows you to rewire your AG5, so that you can take your AG5 with you anywhere, plug it into any computer, and viola! it always remembers your custom remapping.

1.1  Status

So far, I’ve determined the microcontroller signals for all buttons, lights (LEDs), and mouse encoders (see Device documentation). I am currently building a MON08 programmer circuit (see Programming) to be able to reprogram the on-chip flash on the microcontroller.

1.2  Features

Anything is possible because you control the firmware!

  • Make any key emit any character or signal.
  • Change the sensitivity of the trackball.
  • Transform any key into a special shift modifier.
  • Light up any LED for whatever reason.
  • Make the dreaded CapsLock key emit a signal.
  • Save/load your custom remap directly onto the AG5 through USB.

1.3  License

(the ISC license)

Copyright 2007 Suraj N. Kurapati sunaku@gmail.com

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

1.4  Mailing list

To subscribe, send an e-mail with “subscribe” in the subject to openag5-talk-request@lists.tuxfamily.org and a confirmation e-mail will be sent to you.

To unsubscribe, simply send an e-mail with ”unsubscribe” in the subject to the address shown above.

Chapter 2
Setup

Loading the OpenAG5 firmware onto an AG5 requires opening the case, soldering, and other forms of tinkering. For this reason, please note that I am not responsible for any damage or loss that may result from the installation or use of this firmware.

With that said, you are welcome to ask for help in the project mailing list if you run into any trouble during installation.

2.1  Requirements

TODO

2.2  Installation

TODO

Chapter 3
Device documentation

This chapter presents documentation about the internals of the AG5, which I painstakingly reverse-engineered so that you don’t have to. :-)

3.1  Microcontroller

The microcontroller onboard my AG5 was covered by a white sticker with the following text printed on it:

v1.1
061214
23EF

When I peeled the sticker off, the following text was revealed:

MC908JB8FBE
3K45H
CTQH0610

This indicates that the microcontroller on my AG5 is a Freescale MC68HC908JB8, which is a member of the HC08 family. You can obtain the technical data sheet for this microcontroller directly from Freescale.

Figure 1.  Microcontroller pinout diagram

This diagram [1, page 32] shows the pinout for the microcontroller on my AG5.

3.1.1  Programming

Because the microcontroller on the AG5 is a member of the HC08 family, we can use the MON08 monitor mode (which is common to all family members) to program it.

Figure 2.  Connection points for microcontroller programming

This image shows the connection points for programming the microcontroller via the MON08 monitor mode interface.

I tried to find as many off-chip connection points as possible because soldering wires to the tiny microcontroller pins is difficult.

Figure 3.  Schematic for MON08 programmer

This diagram [2, page 9] is a schematic for the MON08 programmer circuit, which allows us to program the microcontroller through the MON08 monitor mode interface.

3.2  Button wiring

A circular receptor composed of two electrical contacts (see Electrical contacts in a button receptor) can be found beneath every button on the AG5.

Figure 4.  Electrical contacts in a button receptor

The inner contact (shown in red) appears like a plus sign (+) in the middle of the receptor. It is surrounded by the outer contact (shown in gold) which appears like a circle.

When a button is pushed, a rubber pad (coated with material that conducts electricity) comes down and sits upon the receptor. This connects the two electrical contacts in the receptor, causing current to flow through the contacts. The microcontroller then senses this current flow and knows that a button has been pushed. In addition, the microcontroller also knows which button was pushed because every pair of electrical contacts is connected to a unique pair of signals (see Button contacts and microcontroller signals) on the microcontroller.

Button contacts and microcontroller signals lists the microcontroller signals corresponding to each pair of electrical contacts for every button on the AG5. You can determine or verify these connections for yourself through the use of a continuity tester.

Notice that the white shift buttons are actually composed of two smaller buttons. The reason for this might be that the AG5 inventors ran out of room on the secondary PCB and so, they simply chose to use two smaller button receptors instead of a normal one.

Table 1.  Button contacts and microcontroller signals

ButtonLabelInner contactOuter contact
K1MPTB0PTA0
K2HPTB1PTA0
K3UPTC1PTA6
K4NPTC1PTA4
K5, (comma)PTB4PTA0
K6| (pipe)PTB5PTA0
K7. (period)PTB6PTA0
K8OPTB7PTA0
K9BPTB4PTA3
K10PPTB5PTA3
K11GPTB6PTA3
K12RPTB7PTA3
K13TPTC1PTA5
K14FPTC0PTA7
K15EPTB2PTA3
K16DPTB3PTA3
K17SPTB0PTA4
K18WPTB1PTA4
K19APTB2PTA4
K20QPTB3PTA4
K21JPTB4PTA4
K22VPTB5PTA4
K23CPTB3PTA7
K24YPTB2PTA7
K25KPTB0PTA7
K26LPTB1PTA7
K27XPTC1PTA1
K28ZPTC1PTA0
K29EntPTB4PTA7
K30BkSpacePTB7PTA7
K31TabPTB6PTA7
K32SpacePTB5PTA7
K33ARightWhiteShiftTopPTC4PTA2
K33A1RightWhiteShiftBottomPTC4PTA2
K33BLeftWhiteShiftTopPTC4PTA3
K33B1LeftWhiteShiftBottomPTC4PTA3
K34ALeftGreenShiftPTA5PTC5
K34BRightGreenShiftPTC5PTA5
K35ARightRedShiftPTA4PTC5
K35BLeftRedShiftPTA4PTC5
K36Win%PTC3PTA1
K37EscPTB1PTA1
K38PrtScPTC1PTA2
K39Alt/OptPTC7PTA7
K40CtrlPTC6PTA6
K41NumLockPTB3PTB1
K42FnLockPTB4PTA1
K43PausePTC1PTA3
K44DelPTB5PTA1
K45CapsLockPTB6PTA1
K46MouseClickTopPTC2PTA0
K47MouseClickBottomPTC3PTA5

3.3  Mouse wiring

  • Horizontal movement is detected by the top mouse encoder, which is connected to the PTD0 and PTD1 signals on the microcontroller.

  • Vertical movement is detected by the bottom mouse encoder, which is connected to the PTD2 and PTD3 signals on the microcontroller.

Figure 5.  Front face of secondary PCB

I apologize for the poor quality of this photo, but I have already placed this PCB back into my AG5 and it’s far too much work to open it up again for the sole purpose of taking a better photo. :-/

3.4  Light wiring

Light contacts and microcontroller signals lists the corresponding microcontroller signals for every LED(Light Emitting Diode) (a small light bulb) on the outer face of the AG5.

Table 2.  Light contacts and microcontroller signals

LightSignal
nlPTD7
paPTD5
clPTD4
flPTD6

References

  1. Freescale Semiconductor, M68HC08 Microcontrollers Technical Data, 2005 (Rev. 2.3), [cited 23 December 2007], Available at http://www.freescale.com/files/microcontrollers/doc/data_sheet/MC68HC908JB8.pdf
  2. John Suchyta, Low-Cost Programming and Debugging Options for M68HC08 MCUs, October 2002 (Rev. 1), [cited 23 December 2007], Available at http://www.freescale.com/files/microcontrollers/doc/app_note/AN2317.pdf



This document was generated by ERBook 9.2.0 on 2009-11-07 13:14:55 -0800 using the following resources.

Resource Origin License
here_frag important warning caution note tip quote nav_here nav_prev nav_next nav_list Tango Icon Theme

© 2005 Tango Desktop Project

Creative Commons Attribution-ShareAlike 2.5 License Agreement
hyperlink MediaWiki Monobook Skin

© 2007 MediaWiki contributors

GNU General Public License, version 2

Valid XHTML 1.0 Strict Valid CSS!