IR Software Functional Specification

	Distribution:	COMPANY CONFIDENTIAL
    
	Project:	NC Model 1
	Issue:		0.07
	Author(s):	Jonathan Harris, Chris Chambers, Steve Cormie (edited by DWalker)
	Date:		18-Sep-97
	Last Issue:	0.06
      

Contents.

• History
• Outstanding issues
• Overview
• Technical background
• User interface
• Programmer interface
• Standards
• Data interchange
• Data formats
• External dependencies
• Acceptance test
• Development test strategy
• Product organisation
• Future enhancements
• References

History

	0.01 SMC 12-Apr-96 First created.
	0.02 JRH 16-Apr-96 Merged in: overview,
	                   outstanding issues in supporting device numbers,
	                   some changes to layout and hardware scheme (1).
	0.03 JRH 01-Jul-96 Airmouse have decided to go for UART i/f.
	                   Merged in IR Software Protocol document ver. 0.11.
	0.04 JRH 04-Jul-96 Moved the new keyboard buffer codes out into the
	                   Misc spec. Added configuration setting.
	0.05 JRH 12-Sep-96 All changed for new SolutioNet protocol.
	0.06 JRH 16-Oct-96 Defined keyboard scan codes.
	                   Relative pointer format: now has Resend bit.
	                   Keyboard format: now has Up/Down bit.
	                   Added more info about each type of data packet.
      

Outstanding issues

• The IRRemote module in the first NCOS release will only support the A-Z handset. NCs which have access to a file server may download replacement IRRemote modules with support for a wider range of IR peripherals.
• Provision has been made in the IR hardware protocol for communicating arbitrary data bytes between the NC and peripherals. These packet types are still under discussion and so are not included in this document.

Overview

• A-Z handset
• A-Z handset with pointer
• QWERTY keyboard with or without trackball

• Dual joysticks

The IR system will `seamlessly' support multiple IR peripherals at the same time (ie the user will be able to switch between say a handset and a wired or IR keyboard without reconfiguring the system).

In addition the NC and IR peripherals will be configurable with a 4 bit `family' number to allow up to 15 matched NC / peripheral combinations to be used in proximity to each other without cross-talk.

This document describes the software required to support IR peripherals on the Network Computer Model 1.

Technical background

The NCOS IRRemote module will communicate with the front-end (8051-compatible) micro via the NC's second serial port interface (which is routed internally to the IR system) using the protocol defined below.

Handset

The IRRemote module will contain territory and handset layout-specific tables to convert handset scan-codes to keyboard buffer codes which it will insert into the keyboard buffer using SWI OS_Byte 153. Initially the driver will support only the US and UK territories, and only handset layout number 0 (as used by the initial A-Z handset). New keyboard buffer codes will be returned for keys which do not exist on normal keyboards.

Keyboard

The IRRemote module will register itself as a PC-type keyboard. It will contain a table to convert scan-codes to RISC OS low-level key numbers and will issue Key up/down events using SWI OS_CallAVector to call KEYV. This allows the driver to make use of territory-specific keyboard mappings.

Peripheral family

The IRRemote module will determine its family number from non-volatile memory and will instruct the front-end micro to reject IR packets from peripherals with a different family number.

User interface

*Configure IRFamily

Sets the configured IR family number.

Syntax

	*Configure IRFamily <1-15> | Any
      

Parameters

	<1-15>		family number
	Any		accept any peripheral
      

Use

*Configure IRFamily limits the peripherals that this NC will communicate with to those which have the given family number.

You can also set a value of 0 or Any, in which case the NC will accept data from any IR peripheral.

Programmer interface

There is no programmer interface; application programmers will see mouse and key events using the normal RISC OS SWIs

Standards

None applicable.

Data interchange

None applicable.

Data formats

The IRRemote module and front-end micro will communicate via the second serial port using an asymmetric protocol consisting of single-byte commands and multi-byte data packets. Commands are written to the micro by the IRRemote module. Data packets are read from the micro by the IRRemote module.

Commands

The following commands are sent by the IRRemote module to the front-end micro:

Reset

The IRRemote module will transmit a Reset command on initialisation. Upon receiving this command the front-end micro will re-initialise itself and start to transmit incoming IR data packets up to the ARM. This command also sets the NC's family number.

Where:

	F3-F0	Family number
      

Halt

This command instructs the front-end micro to stop transmitting packets up to the ARM until it receives a reset command. The front-end micro will be in a halted state after power-up.

Data packets

Data packets are only transmitted up to the ARM after the underlying IR packets have been filtered for family number and the checksums verified. The front-end micro will not send packets from a uni-directional peripheral to the ARM unless they are preceded by a Basic Peripheral Identification packet from the peripheral.

All data packets passed up to the ARM consist of three bytes of data encoded into a four byte quantity:

Where:

	Bx.y	Bit y of data byte x
      

Peripheral Identification

IR peripherals must identify themselves to the NC before sending data by sending a Basic Peripheral Identification Packet optionally preceded by an Extended Peripheral Identification Packet. Peripherals must also re-identify themselves before sending data if they have not identified or re-identified themselves in the last five seconds.

The front-end micro will assign the peripheral a Tag Value in the range 4-13 and this Tag Value will be present in all data packets from this peripheral.

Uni-directional peripherals cannot be assigned an arbitrary Tag Value by the front-end micro and must be hardwired or programmed with a tag in the range 0-3. Uni-directional peripherals must send a Basic Peripheral Identification packet before every data packet and are not allowed to send Extended Peripheral Identification packets.

The peripheral identification packets contain a registry number which uniquely identifies the peripheral. The NC will use this number to identify the peripheral's manufacturer, product name, number, type and revision, A/B channel and the data packet format used.

If the front-end micro re-assigns a Tag Value to a new peripheral the IRRemote module will discard any state information that it is holding for that peripheral.

Peripheral Identification - Basic

Where:

	T3-T0	Tag value assigned by front-end micro, or hardwired into
		the peripheral in the case of uni-directional peripheral.
	LOW	Low battery indication (1 = battery low).
	R14-R0	Registry number or low bits of registry number where
		this packet is preceded by an Extended Peripheral
		Identification packet.
      

Peripheral Identification - Extended

Where:

	T3-T0	Tag value assigned by front-end micro.
	R30-R15	High bits of registry number.
      

Keyboard

The same Keyboard Packet is used to report data from handsets and full keyboards and from both uni- and bi-directional peripherals:

Uni-directional:

When a key is depressed a uni-directional peripheral will transmit a Keyboard Packet with the RPT, RSN and UDN bits clear. If the key is still depressed after approximately 1/3s the peripheral will transmit packets with the RPT bit set and RSN and UDN bist clear approximately every 1/10s. The peripheral's repeat rate is used directly by NCOS to generate key auto-repeat.

Bi-directional:

Bi-directional peripherals that use the UDN bit will send a packet with this bit clear when a key is depressed and another packet with this bit set when the key is released. Peripherals which do not use the UDN bit will send packets at least every 1/10s while a key is depressed. The use of the RSN bit is optional for peripherals that do not use the UDN bit. The key auto-repeat rate is determined by the NCOS software.

Where:

	RPT	Key auto-repeat flag (1 = repeat of last key).
	RSN	Key resent due to lack of ACK (1 = resent).
	UDN	Key up/down (1 = up).
	T3-T0	Tag value.
	K7-K0	Key scan code.
	Ctrl	Control modifier key (1 = active).
	Shift	Shift modifier key (1 = active).
	Alt	Alt modifier key (1 = active).
	Fn	Fn modifier key (1 = active).
	M	Reserved modifier key.
	X	Reserved, must be 0.
      

Absolute Pointer

Peripherals that report an absolute pointer position will send Absolute Pointer packets either repeatedly or only when the pointer has moved. Peripherals will send packets at least every 1/10s while a button is depressed.

Where:

	B1	Left button (1 = active).
	B2	Right button (1 = active).
	T3-T0	Tag value.
	X8-X0	X coordinate (0-511, 0 = left edge).
	Y8-Y0	Y coordinate (0-511, 0 = bottom edge).
      

Relative Pointer

Peripherals that report relative pointer movement will send Relative Pointer packets either repeatedly or only when the pointer has moved. Peripherals will send packets at least every 1/10s while a button is depressed.

Use of the RSN bit is optional but recommended to ensure that the same pointer delta is not applied twice to the pointer position.

Where:

	RSN	Packet resent due to lack of ACK (1 = resent).
	B1	Left button (1 = active).
	B2	Right button (1 = active).
	T3-T0	Tag value.
	X7-X0	X delta (2s complement: -128 - 127).
	Y7-Y0	Y delta (2s complement: -128 - 127).
	X	Reserved, must be 0.
      

Tag Retirement

If the front-end micro is running short of Tag Values to assign to new peripherals it may claim back (`retire') a Tag Value already assigned to a peripheral if that peripheral has not been active in the previous ten seconds. In the case where the front-end micro has no free Tag Values and cannot retire any assigned Tag Values it will NAK all Peripheral Identification packets from peripherals which have not been assigned a tag.

After retiring one or more Tag Values the front-end micro will send the following packet to the ARM. The IRRemote module will discard any state information that it is holding for peripherals whose tags are retired.

Where:

	An	Current tag usage for tag n (1 = in use).
	X	Reserved, must be 0.
      

Scan-code mappings

Keyboard mappings

The front-end micro will supply the following keyboard scan codes. The IRRemote module will convert these scan codes to RISC OS low-level key numbers which will be converted by the OS to keyboard buffer codes in a territory-dependent fashion. The symbols shown against each scancode in this table apply to the US and UK territories. NCOS keyboard drivers for other territories may expect different symbols to be printed on some of these keys.

Handset mappings

The front-end micro will supply the following handset key scan codes. The IRRemote module will convert these scan codes directly to RISC OS low-level key numbers.

Product organisation

The IRRemote module sources will form part of the NC ROM build tree.

Future enhancements

• Support for joystick and data peripherals.
• Addition of a Configuration utility to the NC user-interface. This will allow the user to configure the NC's IR family number (this raises the question of how the user will gain access to a NC which has been configured with a family number which does not match that of the peripheral in the user's possession.

References

Low-level internal key numbers

RISC OS 3 PRM page 1-156 (not online)

Keyboard buffer codes

RISC OS 3 PRM pages 1-891 to 1-893 (not online)