Editing SmartBox AlbertLink

 <nowiki>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
        note    byte = channel reference (1 to 10)
        note    string = file name
        note    the file should then be opened and a FileBack event made or a
                Error event, to signal a error

Close           2 +byte
        note    byte = channel reference

Store           3 +byte +data (terminated by NUL)
        note    byte = channel reference
        note    data = data to put to file

Trace                   old:
                4 +string
        note    string = string to print
                        new:
                4 +string +double byte
        note    string = procedure name
        note    double byte = line number
        return  byte
        note    byte = flag
                        : 0, no stepping
                        : 1, wait for tracecont

Print           5 +[characters terminated by NUL, CR expand to CRLF]
        note    do not CRLF after this, keep cursor position

Error           6 +string +string2 +string3       (to change)
        note    string = procedure name (blank if from cmd line)
        note    string2 = error
        note    string3 = line containing error (blank if from cmd line)

Ask             7 +byte
        note    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
        note    this means that command mode is ready

Build           10 +string
        note    string = proc to edit

Edit            11 +string
        note    string = proc to edit

Quit            12
        note    user has typed QUIT, use Quit to quit system

TraceFl         13 +byte
        note    byte = trace flag (0 -> off, #0 -> on)

Load            14 +string
        note    string = filename
        note    use Put
        note    use Error for filing errors
        note    string can be blank

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

Control         16 +byte
        note    byte = control parameter, if out of range, return 0 and then
                use Error
        return  byte
        note    byte = value of control option

Rtc             17
        return  byte +byte2 +byte3 +byte4
        note    byte = hours
        note    byte2 = minutes
        note    byte3 = seconds
        note    byte4 = centiseconds
        note    cause Error AFTER returning 0 for all if not supported.

Printer         18
        note    as Print

Altered         19 +byte
        note    byte = flag
                        bit 0 : procedure list changed
                        bit 1 : labels changed
        note    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
        note    byte = fn value

Prompt          23 +string
        note    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
        note    byte = setup byte
        note    as startup setup flag

List            2
        return  [string .....] until string is blank
        note    this returns a list of procedures terminated by a blank

NameCode        3 +string
        note    *NB* doesn't return normal link 0 acknowledge.
        note    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
        note    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
        note    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
        note    causes escape condition

Quit            7
        note    causes AlbertLink to quit

Cmd             8 +string
        note    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
        return  byte = sensor a id
                byte = sensor b id
                byte = sensor c id
                byte = sensor d id
        note    perform once a second or so to re-check the sensors

SteadyLine      11 +byte +string
        note    byte = flag
                          0 : do not use labels
                          1 : use labels
                        255 : use LBLS setting
        return  string = expanded line
        note    use in editor to expanded abbreviated commands

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

SetPort         13 +byte +byte2
        note    byte = bits to set
        note    byte2 = bits to mask

Error           14 +string
        note    string = error to cause

Version         15
        return  string = version string

Sleep           16
        note    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
        note    string = input line

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

WriteLabel      20 +string1 +string2 +byte
        note    string1 = source label
        note    string2 = label
        note    byte = flag
                        : 0, hard label
                        : 1, soft label
        return  byte
        note    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
        note    byte/2 = free memory

TraceCont       22
        note    this causes procedure execution to continue from a stopped trace

Clock           23 +byte
        note    byte = flag
                        : 0, stop clock
                        : 1, start clock
                        : 2, reset clock

PromptBack      24
        note    send this when the user has clicked on the "prompt"

FileBack        25 +byte
        note    byte = flag
                        : 0, cannot open file
                        : 1, file opened
        note    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.</nowiki>