Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File13.13.3.5  Example: no|Link's XAcc protocol                        TOS

The no|Link accessory was conceived for the control of infra-red 
devices and contains an XAcc communication layer for the control by 
special applications. At present the Media-Link interface of Catch 
Computer is supported. A further adaptation for the no|Remote 
interface of no|Software is in preparation (at the time this was 
written).

The no|Link accessory administers all information required for the 
control of the infra-red or other hardware. Each hardware-dependent 
code (e.g. an infra-red signal) is assigned a command, and for each 
device (e.g. a video recorder) there exists a list of such commands.

For example, if an application for the remote control of a video 
recorder wants to send an infra-red signal for the 'Play' key, then it 
sends no|Link an XAcc message, in which the command 'send', the device 
<VIDEORECORDER> and the command <PLAY> are coded.

So that an application can communicate completely with no|Link, it 
must support the Request/Reply protocol, which is made known by an 
Extended feature 'RQ' in the XDSC description. Only in this way is it 
possible to maintain the list of the no|Link installed devices.

If the application also wants to receive codes from the accessory 
(only possible with suitable hardware), then the XDSC description must 
contain additionally an Extended feature 'RR' (Remote Receive). All 
applications that want to work with no|Link have to support the XAcc 
Level/Message group 1.

As application type the no|Link accessory receives in XDSC '\2RC' 
(Remote Control).

The complete XAcc identification of no|Link at present is as follows 
(in C-syntax, using the original German):

    char xaccNoLinkIdent[] =    "Infrarot Manager\0"
                                "XDSC\0"
                                "1Fernsteuerschnittstelle\0"
                                "2RC\0"
                                "XRQ\0"
                                "NnoRci\0";

A possible XAcc identification for a no|Link application could look 
like this:

    char xaccIdentstring[] =    "VideoControl\0"
                                "XDSC\0"
                                "1Video Fernbedienung\0"
                                "XRQ\0"
                                "Nno|Video ACC\0";

The communication between the application and the no|Link accessory is 
mainly via ACC_TEXT messages.

The accessory at present understands the following commands, which 
have to be sent as a string by means of an ACC_TEXT message (where <X> 
:= <device>:<command>):

 "S <X>"  Sending of a command, e.g: 'S VIDEO:PLAY'.

 "P <X>"  Preparation of a command, e.g: 'P VIDEO:PLAY'. With this the 
          infra red hardware is informed of the code for this command, 
          but it is not yet sent

 "S"      Sending of the last prepared command

 "T <X>"  Test of the existence of a command

          Particularly at a new installation of a remote control 
          application, all devices and commands that this application 
          uses should be communicated to the accessory!

          If no|Link does not know the supplied command, the user is 
          invited to activate the required 'learning procedure', or to 
          assign the new command to one already present.

          Each remote control application should contain a function 
          that allows the user to 'test' all supported commands - 
          preferably via an 'Install' button.

The test function is the only one that may lead to interaction with 
the user in some circumstances. All others issue no output.

As reply the application receives an ACC_ACK message, in which the 
success or otherwise of handling the command is noted in msg[3]:

 1 Operation was successful

 0 Device/command is not present, or error in the handling

Device and command names may be up to 32 characters long and may not 
contain a ':'. No regard is paid to case, i.e. capitals and lower case 
characters are not differentiated.

An application can request a list of installed devices from the 
accessory. For this the application has to understand the new XAcc 
Request/Reply protocol (see above, or XACC.H).

To request the list, the application sends a ACC_REQUEST to the 
accessory, where the message must be constructed as follows:

    msg[0] = ACC_REQUEST (0x480)
    msg[1] = apid
    msg[2] = 0
    msg[3] = 0x04       /* Data-type: Code */
    msg[4] = 'D'        /* 'D' represents 'devices' */
    msg[5] = 0
    msg[6] = 0
    msg[7] = 0

As reply the application receives an ACC_ACK message with msg[3] == 0 
if an error has occured, or on success an ACC_REPLY message:

    msg[0] = ACC_REPLY (0x481)
    msg[1] = apID of no|Link
    msg[2] = 0
    msg[3] = 0x02       /* Data-type: Environment string */
    msg[4]+msg[5] = Pointer to globally accessible memory containing the
                    list of the devices in the following format:
                           "DEVICEINFOS:\0device1\0device2\0"
    msg[6]+msg[7] = LONG value, specifying the size of the buffer
                    (inclusive of the terminating two NULL-bytes)


The receipt of an ACC_REPLY message must be confirmed subsequently 
with an ACC_ACK message, so that the no|Link accessory can release its 
resources again!