Editing SmartBox AlbertLink

AlbertLink Link Protocol (Release 11)

== Startup ==

After AL has been downloaded and called the first thing back will be a engine release number (one byte), and known setup flags (one byte) which you should check that the "new" flags you want are set. If the engine number is wrong or the setup flags you want aren't set then send a 0 and AlbertLink will quit itself, else send ANYTHING but a 0. Then send your setup flags (one byte), which will engage the various "new" options.

ie:

{|
| send jobcode for AlbertLink || &rarr; ||
|-
|                             || &larr; || engine number
|-
|-
|                             || &larr; || known setup flags
|-
| flag for continue or not    || &rarr; ||
|-
| setup flags wanted          || &larr; ||
|}

== Setup Flags ==

The 8 setup flags are setup as such:

{|class="wikitable"
! bit !! if set
|-
| 0   ||  use new trace system
|-
| 1   ||  enable procedure/label change checking
|-
| 2   ||  enable custom commands
|-
| 3   ||  enable prompt
|-
| 4   ||  shit computer
|-
| 5   ||  enable "get" line count
|}

== Idle ==

At this point the system is idling, both ends are waiting to originate a "event" or receive one.

The remote end should check the serial port as often as possible, if it detects a byte then it should read it, check it is in range, and transmit a 0 (byte) back, then it should do one of the following "event" types according to the byte it received:

=== File ===

1 +byte +string

* byte = channel reference (1 to 10)
* string = file name
* the file should then be opened and a FileBack event made or a Error event, to signal a error

=== Close ===

2 +byte

* byte = channel reference

=== Store === 

3 +byte +data (terminated by NUL)

* byte = channel reference
* data = data to put to file

=== Trace ===

==== Old ====

4 +string

* string = string to print

==== New ====

4 +string +double byte

* string = procedure name
* double byte = line number

Return: byte
* byte = flag
*: 0, no stepping
*: 1, wait for tracecont

=== Print ===

5 +[characters terminated by NUL, CR expand to CRLF]

* do not CRLF after this, keep cursor position

=== Error ===

6 +string +string2 +string3       (to change)

* string = procedure name (blank if from cmd line)
* string2 = error
* string3 = line containing error (blank if from cmd line)

=== Ask ===

7 +byte

* byte = 'S', 'N' or 'T' (input type)

Return
* use AskBack to return input string

=== Inkey ===

8

Return: byte
* 0 -> no key
* #0 -> key value

=== Cmd ===

9

* this means that command mode is ready

=== Build ===

10 +string

* string = proc to edit

=== Edit ===

11 +string

* string = proc to edit

=== Quit ===

12

* user has typed QUIT, use Quit to quit system

=== TraceFl ===

13 +byte

* byte = trace flag (0 -> off, #0 -> on)

=== Load ===

14 +string

* string = filename
* use Put
* use Error for filing errors
* string can be blank

=== Save ===

15 +string +string2

* string = filename
* string2 = procedure to save (or blank for all)
* use Error for filing errors
* use Get/List to get procedures

=== Control ===

16 +byte

* byte = control parameter, if out of range, return 0 and then use Error

Return: byte
* byte = value of control option

=== Rtc ===

17

Return: byte +byte2 +byte3 +byte4
* byte = hours
* byte2 = minutes
* byte3 = seconds
* byte4 = centiseconds

Cause Error AFTER returning 0 for all if not supported.

=== Printer ===

18

* as Print

=== Altered ===

19 +byte

* byte = flag
*: bit 0 : procedure list changed
*: bit 1 : labels changed

when you get this you should use List and/or ReadLabels to update yourself

=== Custom ===

20 +data (NUL terminated)

=== Custom2 ===

21 +data (NUL terminated)

=== Customfn ===

22 +string

Return : byte
* byte = fn value

=== Prompt ===

23 +string

* string = prompt string

NB: "string" is a group of characters terminated by CR.

Any other codes should be ignored.

== Remote "events" ==

The remote end also has "events" which it can originate, to start an event, transmit the "event" code and wait until you receive a 0 (byte), ignore all other bytes received (the remote end has priority) and then you can transmit any other bytes needed:

=== Setup ===

1 +byte

* byte = setup byte
* as startup setup flag

=== List ===

2

Return  [string .....] until string is blank

* this returns a list of procedures terminated by a blank

=== NameCode ===

3 +string

* '''NB''' doesn't return normal link 0 acknowledge.
* Emulates the normal OS NameCode, quiting AlbertLink if the remote doesn't try to check for AlbertLink and going out of sleep if it does try for AlbertLink

=== Get ===

4 +byte +string

* byte = flag
*: 0 : do not use labels
*: 1 : use labels
*: 255 : use LBLS setting

==== Old ====

Return byte:
* 0 &rarr; no such procedure else procedure terminated by 0ffh

==== New ====

Return:
* byte = 0 -> no such procedure
* 1 +byte2 +byte3 +procedure &rarr; procedure found

byte2/3 is number of lines in procedure

=== Put ===

5 +string +[procedure strings terminated by 0ffh]

Return: byte
* 0 &rarr; ok
* 1 &rarr; bad name
* 2 &rarr; no room
* 3 &rarr; bad data

=== Escape ===

6

* causes escape condition

=== Quit ===

7

* causes AlbertLink to quit

=== Cmd ===

8 +string

* performs a raw command, use only after flagged cmd ready else any running procedure will be stopped

=== GetPorts ===

9

Return

* byte = run mode (1 = running procedure)
* byte = inputs
* byte = outputs
* byte = motors
* byte = adc 1
* byte = adc 2
* byte = adc 3
* byte = adc 4
* byte = clock (hours)
* byte = clock
* byte = clock
* byte = clock (cs)

=== GetPS ===

10

Return 
* data as GetPorts
* byte = sensor a id
* byte = sensor b id
* byte = sensor c id
* byte = sensor d id
 
Perform once a second or so to re-check the sensors

=== SteadyLine ===

11 +byte +string

* byte = flag
*: 0 : do not use labels
*: 1 : use labels
*: 255 : use LBLS setting

Return string
* expanded line
 
use in editor to expanded abbreviated commands

=== TraceFl ===

12 +byte
* byte = new trace setting and causes Trace "events"

=== SetPort ===

13 +byte +byte2

* byte = bits to set
* byte2 = bits to mask

=== Error ===

14 +string

* string = error to cause

=== Version ===

15

Return string
* version string

=== Sleep ===

16

causes AlbertLink to sleep the remote link, waking up with a normal AlbertLink startup

=== CheckSensors ===

17

Return

* byte = sensor a id
* byte = sensor b id
* byte = sensor c id
* byte = sensor d id

=== AskBack ===

18 +string

* string = input line

=== ReadLabels ===

19

Return [+string1 (+string2) .......]
* string1 = source label
* string2 = label (not sent if string1 is blank)
* string2 terminated by 0 for hard label and 128 for soft label
* end of list terminated by string1 being blank

=== WriteLabel ===

20 +string1 +string2 +byte

* string1 = source label
* string2 = label
* byte = flag
*: 0, hard label
*: 1, soft label
 
Return byte

* byte = flag
*: 0, okay
*: 1, bad source label
*: 2, bad label
*: 3, label too long
*: 4, label exists as a procedure
*: 5, can't overwrite hard label with a soft label

=== FreeMem ===

21

Return byte +byte2
* byte/2 = free memory

=== TraceCont ===

22

This causes procedure execution to continue from a stopped trace

=== Clock ===

23 +byte

* byte = flag
*: 0, stop clock
*: 1, start clock
*: 2, reset clock

=== PromptBack ===

24

Send this when the user has clicked on the "prompt"

=== FileBack ===

25 +byte

* byte = flag
*: 0, cannot open file
*: 1, file opened

Used in reply to File

Print, Trace, SteadyLine, Get and Error surround any tokens with 1 to start token and 2 to finish token. Put and SteadyLine will remove them automatically before processing.