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 | → | |
| ← | engine number | |
| ← | known setup flags | |
| flag for continue or not | → | |
| setup flags wanted | ← |
Setup Flags
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
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
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 → no such procedure else procedure terminated by 0ffh
New
Return:
- byte = 0 -> no such procedure
- 1 +byte2 +byte3 +procedure → procedure found
byte2/3 is number of lines in procedure
Put
5 +string +[procedure strings terminated by 0ffh]
Return: byte
- 0 → ok
- 1 → bad name
- 2 → no room
- 3 → 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.