SmartBox AlbertLink
AlbertLink Link Protocol (Release 11)
Startup[edit]
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 | → | |
| ← | engine number | |
| ← | known setup flags | |
| flag for continue or not | → | |
| setup flags wanted | ← |
Setup Flags[edit]
The 8 setup flags are setup as such:
| 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[edit]
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[edit]
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[edit]
2 +byte
- byte = channel reference
Store[edit]
3 +byte +data (terminated by NUL)
- byte = channel reference
- data = data to put to file
Trace[edit]
Old[edit]
4 +string
- string = string to print
New[edit]
4 +string +double byte
- string = procedure name
- double byte = line number
Return: byte
- byte = flag
- 0, no stepping
- 1, wait for tracecont
Print[edit]
5 +[characters terminated by NUL, CR expand to CRLF]
- do not CRLF after this, keep cursor position
Error[edit]
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[edit]
7 +byte
- byte = 'S', 'N' or 'T' (input type)
Return
- use AskBack to return input string
Inkey[edit]
8
Return: byte
- 0 -> no key
- #0 -> key value
Cmd[edit]
9
- this means that command mode is ready
Build[edit]
10 +string
- string = proc to edit
Edit[edit]
11 +string
- string = proc to edit
Quit[edit]
12
- user has typed QUIT, use Quit to quit system
TraceFl[edit]
13 +byte
- byte = trace flag (0 -> off, #0 -> on)
Load[edit]
14 +string
- string = filename
- use Put
- use Error for filing errors
- string can be blank
Save[edit]
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[edit]
16 +byte
- byte = control parameter, if out of range, return 0 and then use Error
Return: byte
- byte = value of control option
Rtc[edit]
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[edit]
18
- as Print
Altered[edit]
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[edit]
20 +data (NUL terminated)
Custom2[edit]
21 +data (NUL terminated)
Customfn[edit]
22 +string
Return : byte
- byte = fn value
Prompt[edit]
23 +string
- string = prompt string
NB: "string" is a group of characters terminated by CR.
Any other codes should be ignored.
Remote "events"[edit]
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[edit]
1 +byte
- byte = setup byte
- as startup setup flag
List[edit]
2
Return [string .....] until string is blank
- this returns a list of procedures terminated by a blank
NameCode[edit]
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[edit]
4 +byte +string
- byte = flag
- 0 : do not use labels
- 1 : use labels
- 255 : use LBLS setting
Old[edit]
Return byte:
- 0 → no such procedure else procedure terminated by 0ffh
New[edit]
Return:
- byte = 0 -> no such procedure
- 1 +byte2 +byte3 +procedure → procedure found
byte2/3 is number of lines in procedure
Put[edit]
5 +string +[procedure strings terminated by 0ffh]
Return: byte
- 0 → ok
- 1 → bad name
- 2 → no room
- 3 → bad data
Escape[edit]
6
- causes escape condition
Quit[edit]
7
- causes AlbertLink to quit
Cmd[edit]
8 +string
- performs a raw command, use only after flagged cmd ready else any running procedure will be stopped
GetPorts[edit]
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[edit]
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[edit]
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[edit]
12 +byte
- byte = new trace setting and causes Trace "events"
SetPort[edit]
13 +byte +byte2
- byte = bits to set
- byte2 = bits to mask
Error[edit]
14 +string
- string = error to cause
Version[edit]
15
Return string
- version string
Sleep[edit]
16
causes AlbertLink to sleep the remote link, waking up with a normal AlbertLink startup
CheckSensors[edit]
17
Return
- byte = sensor a id
- byte = sensor b id
- byte = sensor c id
- byte = sensor d id
AskBack[edit]
18 +string
- string = input line
ReadLabels[edit]
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[edit]
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[edit]
21
Return byte +byte2
- byte/2 = free memory
TraceCont[edit]
22
This causes procedure execution to continue from a stopped trace
Clock[edit]
23 +byte
- byte = flag
- 0, stop clock
- 1, start clock
- 2, reset clock
PromptBack[edit]
24
Send this when the user has clicked on the "prompt"
FileBack[edit]
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.