SmartBox AlbertLink: Difference between revisions

From Smart Box
Jump to navigation Jump to search
(Created page with " <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 "ne...")
 
(Converted plaintext documentation to markdown)
 
Line 1: Line 1:
<nowiki>AlbertLink Link Protocol (Release 11)
AlbertLink Link Protocol (Release 11)


Startup
== 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.
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:
ie:
        send jobcode for AlbertLink    >
                                        <        engine number
                                        <        known setup flags
        flag for continue or not        >
        setup flags wanted              >


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


The 8 setup flags are setup as such:
== Setup Flags ==
        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


The 8 setup flags are setup as such:


  Idle
{|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
|}


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


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:
At this point the system is idling, both ends are waiting to originate a "event" or receive one.


File            1 +byte +string
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:
        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
=== File ===
        note    byte = channel reference


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


Trace                  old:
* byte = channel reference (1 to 10)
                4 +string
* string = file name
        note    string = string to print
* the file should then be opened and a FileBack event made or a Error event, to signal a error
                        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]
=== Close ===
        note    do not CRLF after this, keep cursor position


Error          6 +string +string2 +string3      (to change)
2 +byte
        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
* byte = channel reference
        note    byte = 'S', 'N' or 'T' (input type)
        return  use AskBack to return input string


Inkey          8
=== Store ===
        return  byte = 0 -> no key, #0 -> key value


Cmd            9
3 +byte +data (terminated by NUL)
        note    this means that command mode is ready


Build          10 +string
* byte = channel reference
        note    string = proc to edit
* data = data to put to file


Edit            11 +string
=== Trace ===
        note    string = proc to edit


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


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


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


Save            15 +string +string2
==== New ====
        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
4 +string +double 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
* string = procedure name
        return  byte +byte2 +byte3 +byte4
* double byte = line number
        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
Return: byte
        note    as Print
* byte = flag
*: 0, no stepping
*: 1, wait for tracecont


Altered        19 +byte
=== Print ===
        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)
5 +[characters terminated by NUL, CR expand to CRLF]


Custom2        21 +data (NUL terminated)
* do not CRLF after this, keep cursor position


Customfn        22 +string
=== Error ===
        return  byte
        note    byte = fn value


Prompt          23 +string
6 +string +string2 +string3      (to change)
        note    string = prompt string


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


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


Any other codes should be ignored.
7 +byte


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


Remote "events"
Return
* use AskBack to return input string


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:
=== Inkey ===


Setup          1 +byte
8
        note    byte = setup byte
        note    as startup setup flag


List            2
Return: byte
        return  [string .....] until string is blank
* 0 -> no key
        note    this returns a list of procedures terminated by a blank
* #0 -> key value


NameCode        3 +string
=== Cmd ===
        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
9
        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]
* this means that command mode is ready
        return  byte = 0 -> ok, 1 -> bad name, 2 -) no room 3 -> bad data


Escape          6
=== Build ===
        note    causes escape condition


Quit            7
10 +string
        note    causes AlbertLink to quit


Cmd            8 +string
* string = proc to edit
        note    performs a raw command, use only after flagged cmd ready else
                any running procedure will be stopped


GetPorts        9
=== Edit ===
        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
11 +string
        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
* string = proc to edit
        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
=== Quit ===
        note    byte = new trace setting and causes Trace "events"


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


Error          14 +string
* user has typed QUIT, use Quit to quit system
        note    string = error to cause


Version        15
=== TraceFl ===
        return  string = version string


Sleep          16
13 +byte
        note    causes AlbertLink to sleep the remote link, waking up with a
                normal AlbertLink startup


CheckSensors    17
* byte = trace flag (0 -> off, #0 -> on)
        return  byte = sensor a id
                byte = sensor b id
                byte = sensor c id
                byte = sensor d id


AskBack        18 +string
=== Load ===
        note    string = input line


ReadLabels      19
14 +string
        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
* string = filename
        note    string1 = source label
* use Put
        note    string2 = label
* use Error for filing errors
        note    byte = flag
* string can be blank
                        : 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
=== Save ===
        return  byte +byte2
        note    byte/2 = free memory


TraceCont      22
15 +string +string2
        note    this causes procedure execution to continue from a stopped trace


Clock          23 +byte
* string = filename
        note    byte = flag
* string2 = procedure to save (or blank for all)
                        : 0, stop clock
* use Error for filing errors
                        : 1, start clock
* use Get/List to get procedures
                        : 2, reset clock


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


FileBack        25 +byte
16 +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>
* 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.

Latest revision as of 00:15, 12 November 2023

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.

Retrieved from ‘http://smartbox.benryves.com/mediawiki/index.php?title=SmartBox_AlbertLink&oldid=278’