http://mcosre.sourceforge.net/docs/adb_intro.html
12/15/2006

D o c u m e n t a t i o n 


Introduction to Apple Desktop Bus
 
[Home] | [About McOS Re] | [FAQ] | [Changes] | [Progress] | [Documentation] | [Links]


March 1987 was a milestone month for Apple:

One of the most obvious change to the Mac SE and the Mac II has been the redesign of the keyboard and mouse interface. There are no longer 2 separate interfaces for the mouse and the keyboard, each of which could handle only 1 device. Instead the mouse and keyboards are connected through the new Apple Desktop Bus (ADB). All of Apple's new computers use ADB. This interface allows multiple ADB devices to be connected to the computer at the same time. Thus a Mac SE could have 2 keyboards, a mouse and a third-party ADB device (perhaps a graphics tablet) all connected to the computer at the same time.

The Mac SE and the IIgs have a single ADB port while the Mac II has two ports. Each ADB device (except for the mouse which must be the last item on a ADB line) is a pass through device, similar to the SCSI interface. The first ADB keyboard is plugged into the computer's ADB port, the next ADB keyboard is plugged into the previous keyboard (or a second computer port if there is one). Logically up to 15 ADB devices can be connected to a single computer. In practice, however, the signal is not powerful enough to go through that many devices. Depending on what style of keyboard is being used, 3-5 keyboards and a mouse is the maximum configuration.

Introduction to Apple Desktop Bus

The Apple Desktop Bus (ADB) is a low-speed serial bus that connects input devices, such as keyboards, mouse devices, and graphics tablets, to a Macintosh computer or to other hardware equipment. Apple provides a mouse with each Macintosh computer, except for models equipped with a trackball. Additionally, Apple provides various ADB keyboard options, such as the Apple Standard keyboard, the Apple Extended keyboard, and the Apple Adjustable keyboard.

Each ADB device may contain up to four device registers, which you can read from or write to using ADB commands. One of these device registers stores the device's default ADB device address and device handler ID. A default ADB device address is a 4-bit bus address that uniquely identifies the general type of device (such as a mouse or keyboard). An ADB device handler ID (device handler identification) is an 8-bit value that identifies a more specific classification of the device type (such as the Apple Extended keyboard) or specific mode of operation (such as whether the keyboard differentiates between the Left and Right Shift keys).

The Apple Extended keyboard has a default address of $2 and a device handler ID of $02. The Apple Standard keyboard has a default address of $2 and a device handler ID of $01.

An ADB device generally communicates with the OS through a device handler--a set of low level routines designed to interact with a specific ADB device. The Start Manager finds all the devices connected to the computer and places that info into an ADB device table. The ADB device table contains the default ADB device address, device handler ID, and other identifying information for each ADB device. The ADB Manager then initializes any ADB device handlers in the System file. These drivers (stored as "ADBS" resources) will handle any ADB communication.

Two standard ADB device handlers are the mouse driver and the universal keyboard driver. The mouse driver handles all mouse movements. It also handles clicks and issues standard mouseDown and mouseUp events to the Event Manager. While two mice can be connected to the Mac II, the mouse driver was not designed to be able to differentiate between mice and pass this information over to the application (no information is passed in the mouseUp or mouseDown event record to explain which mouse was clicked): the cursor will move with each move of either mouse.

The ADB universal keyboard driver handles any keys being pressed or released on an ADB keyboard. It generates a keyDown or a keyUp event for the Event Manager. However, unlike the mouse driver, the keyboard driver passes along information explaining, not only what key was pressed, but on which keyboard. Prior to the ADB, the message field of a keyDown/keyUp event record contained the ASCII character in the first byte and the virtual key code in the second byte. With ADB, the message field's first and second bytes are the same, while the third byte contains the ADB address of the keyboard that was used.

Four low memory global variables are associated with the ADB Manager:

  KbdLast ($218), byte -- the ADB address of the last keyboard used,
  KbdType ($21E), byte -- the keyboard type of the last keyboard used,
  jADBProc ($6B8), 4 bytes -- the address of ADBReInit preprocessing/postprocessing routine, and
  ADBBase ($CF8), 4 bytes -- the address of Apple Desktop Bus variables.

Default ADB device addresses

Each ADB device has a default address and initially responds to all ADB commands at that address. A default ADB device address uniquely identifies devices of the same type. The currently defined default ADB device addresses have values between $1 and $7. The default address $0 is reserved for the Macintosh computer. Addresses $8 through $E are reserved by the ADB Manager for dynamically relocating devices to resolve address collision.

Default
address		   Device type   Example
$1  Protection devices  Software execution control devices
$2  Encoded devices  Keyboards
$3  Relative-position devices  Mouse devices
$4  Absolute-position devices  Tablets
$5  Data transfer devices  Low-speed ADB modems
$6  Any other  Reserved
$7  Any other  Appliances/miscellaneous
 
 
ADB device handler IDs

The ADB device handler ID further identifies the specific device type or its mode of operation. For example, an Apple Standard keyboard has a device handler ID of 1, while an Apple Extended keyboard has a device handler ID of 2. An ADB device can support several device handler IDs and change its mode of operation according to its current device handler ID.

The Apple Extended keyboard supports two device handler IDs: $02 and $03. (With a device handler ID of $03, the Apple Extended keyboard sends separate key codes for Left and Right Shift keys.)

If an ADB device changes its device handler ID, the ADB Manager does not update the device table. To find out the new device handler ID for a device, you must send the device a Talk Register 3 command.

The ADB Manager, a device handler, or an application can request a device to change its device handler ID by sending it a Listen Register 3 command. An ADB device should respond to a request to change its device handler ID only if it recognizes this device handler ID.

ADB device registers

Each device connected to the Apple Desktop Bus may provide up to four registers for storing data. An ADB device is accessed over the bus by reading from or writing to these registers. Each register may store between 2 and 8 bytes of data. An ADB register may not correspond to a hardware register on the ADB device.

The ADB device registers are numbered 0 through 3. Register 0 and register 3 are predefined. Register 1 and register 2 are device-dependent and can be used for any purpose. For most devices, register 0 is used to hold data that needs to be fetched by the OS. For example, register 0 of the ADB keyboard contains information about the key pressed. The bits in register 3 are predefined by the ADB Manager.

Accessing ADB Manager

ADB devices communicate with the computer using the ADB Manager and special ADB commands (see below). The ADB Manager retrieves new data from the ADB devices and sends it to the appropriate device handler.

An ADB device cannot initiate a data transaction. It must therefore be able to inform the ADB Manager that it needs to transmit new data by asserting a service request signal. In addition, the ADB Manager continually queries ADB devices to see if they have data to send.

The ADB manager can be accessed directly. CountADBs function returns the total number of ADB devices connected to the computer. GetIndADB (based on the device count: from 1 to CountADBs) and GetADBInfo (based on the ADB address of a device) returns information about the device type, ADB address, service routine address, and data area address. Other ADB Manager calls are ADBReInit, ADBOp and SetADBInfo. Any non-standard type of ADB interface would use these commands in it's own ADB device driver.

Whenever the ADB is reinitialized, the ADB Manager reinitializes the ADB device table. If two or more ADB devices share the same default ADB device address when the ADB is building the ADB device table or when the ADB is reinitialized, the ADB Manager assigns each device a new ADB device address until no address conflict exists. This process is known as address resolution.

If necessary, you can directly communicate with an ADB device using the ADBOp routine. You can use this routine for special purposes where you need to directly communicate with an ADB device (for example, to set the LED lights on an Apple Extended keyboard).

ADB commands

An ADB command is a 1-byte value that specifies the ADB device address of a device and encodes the desired action the target device should perform. In some cases, additional data may follow an ADB command.

The ADB Manager can send any of four bus commands to an ADB device. Three of these commands, Talk, Listen, and Flush, are addressed to specific registers on a specific device. The fourth command, SendReset, applies to all ADB devices.

It's important to realize that ADB devices never issue commands to the ADB Manager. At most, the device can assert a service request signal to request that the ADB Manager poll the bus for any devices wishing to transmit data.

An ADB device should respond to a Talk Register 0 command only if the device has new data to send.

Q: How can I turn on/off the LEDs on the Apple Extended Keyboard?

The Apple Extended keyboard maintains the current setting of the LED lights in the lower 3 bits of device register 2. Using the LEDs on the Apple Extended keyboard involves an ADBOp call. It is necessary to preserve the bits in the device register 2 that do not encode the LED state. Device register 2 contains sixteen bits; be sure to change only the three bits that represent the three LED lights.

Once you determine that you have the Apple Extended keyboard (with CountADBs, GetIndADB), you would send the device a Talk Register 2 command to have the device send you the contents of device register 2, manipulate the low three bits to set the LEDs, and then pass the modified device register 2 back (Listen Register 2 command).