Aseba Messages

1. ASEBA Messages
Jacques Supcik <jacques.supcik@hefr.ch>
TIC Technical Report #SUP 15/2
Fribourg, August 18, 2015

2. Document status: work in progress
Copyright © 2015 Jacques Supcik
Haute école d’ingénierie et d’architecture de Fribourg
Bd. de Pérolles 80 - cp 32
1705 Fribourg
Switzerland
This work is licensed under the Creative Commons Attribution 4.0 Interna-
tional License. To view a copy of this license, visit
http://creativecommons.org/licenses/by/4.0/.
ii

3. Contents
Acronyms v
1 Introduction 1
2 Message Format 3
3 Messages 5
3.1 Messages from bootloader control program to a specific node 5
3.1.1 BOOTLOADER_RESET . . . . . . . . . . . . . . . . 5
3.1.2 BOOTLOADER_READ_PAGE . . . . . . . . . . . . . 5
3.1.3 BOOTLOADER_WRITE_PAGE . . . . . . . . . . . . 6
3.1.4 BOOTLOADER_PAGE_DATA_WRITE . . . . . . . . 6
3.2 Messages from node to bootloader control program . . . . . 7
3.2.1 BOOTLOADER_DESCRIPTION . . . . . . . . . . . . 7
3.2.2 BOOTLOADER_PAGE_DATA_READ . . . . . . . . . 7
3.2.3 BOOTLOADER_ACK . . . . . . . . . . . . . . . . . . 8
3.3 Messages from a specific node . . . . . . . . . . . . . . . . 9
3.3.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . 9
3.3.2 NAMED_VARIABLE_DESCRIPTION . . . . . . . . . 10
3.3.3 LOCAL_EVENT_DESCRIPTION . . . . . . . . . . . 10
3.3.4 NATIVE_FUNCTION_DESCRIPTION . . . . . . . . . 11
3.3.5 DISCONNECTED . . . . . . . . . . . . . . . . . . . . 11
3.3.6 VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.7 ARRAY_ACCESS_OUT_OF_BOUNDS . . . . . . . . 12
3.3.8 DIVISION_BY_ZERO . . . . . . . . . . . . . . . . . . 13
3.3.9 EVENT_EXECUTION_KILLED . . . . . . . . . . . . 13
3.3.10 NODE_SPECIFIC_ERROR . . . . . . . . . . . . . . 13
3.3.11 EXECUTION_STATE_CHANGED . . . . . . . . . . . 14
3.3.12 BREAKPOINT_SET_RESULT . . . . . . . . . . . . . 14
3.4 Message from IDE to all nodes . . . . . . . . . . . . . . . . 14
3.4.1 GET_DESCRIPTION . . . . . . . . . . . . . . . . . . 15
3.5 Messages from IDE to a specific node . . . . . . . . . . . . 15
3.5.1 SET_BYTECODE . . . . . . . . . . . . . . . . . . . . 15
3.5.2 RESET . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5.3 RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
iii

4. Contents
3.5.4 PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5.5 STEP . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.6 STOP . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.7 GET_EXECUTION_STATE . . . . . . . . . . . . . . 17
3.5.8 BREAKPOINT_SET . . . . . . . . . . . . . . . . . . 18
3.5.9 BREAKPOINT_CLEAR . . . . . . . . . . . . . . . . . 18
3.5.10 BREAKPOINT_CLEAR_ALL . . . . . . . . . . . . . . 18
3.5.11 GET_VARIABLES . . . . . . . . . . . . . . . . . . . 19
3.5.12 SET_VARIABLES . . . . . . . . . . . . . . . . . . . . 19
3.5.13 WRITE_BYTECODE . . . . . . . . . . . . . . . . . . 20
3.5.14 REBOOT . . . . . . . . . . . . . . . . . . . . . . . . 20
3.5.15 SUSPEND_TO_RAM . . . . . . . . . . . . . . . . . . 20
3.5.16 INVALID . . . . . . . . . . . . . . . . . . . . . . . . . 21
iv

5. Acronyms
IDE Integrated Development Environment. iii, 1, 3, 14, 15, 17, 19, 21
v

7. 1 Introduction
This document describes the messages exchanged between the Thymio
II robot and the Integrated Development Environment (IDE). These mes-
sages are independent from the transport (USB, TCP/IP, …)
1

9. 2 Message Format
Each packet is composed of an header and a body:
length
source
type
0x00
0x02
0x04
0x06
body
…
The length, source, and type are 16 bit unsigned integer encoded as little
endian. The length gives the size of the body in bytes. Note the the size
of the body is not nesessarly a multiple of two, this is why the size is given
in bytes an not in words1
.
“Aseba messages payload data must be 512 bytes or smaller, which means
that the total packets size (len + source + type + payload) must be 518 bytes
or smaller.”
The source is zero for the IDE.
All integer fields in the messages are 16 bit wide encoded in little endian.
This seems unusual for those who are used to work with communication
protocols such as TCP/IP, but it is the natural order in the Thymio II’s CPU.
Some messages contains fields of type String. In this type, the field always
start with an unsigned 8 bit integer giving the size of the string, and the
an array of bytes encoded in Unicode/UTF-8 with the actual characters of
1
In Aseba, 1 word = 2 byte = 16 bit
3

10. 2 Message Format
the string. The size gives the number of bytes and not the length of the
string.
4

11. 3 Messages
3.1 Messages from bootloader control program to a
specific node
3.1.1 BOOTLOADER_RESET
2
source
0x8000
0x00
0x02
0x04
0x06
dest
3.1.2 BOOTLOADER_READ_PAGE
4
source
0x8001
0x00
0x02
0x04
0x06
dest
pageNumber
0x08
5

12. 3 Messages
3.1.3 BOOTLOADER_WRITE_PAGE
4
source
0x8002
0x00
0x02
0x04
0x06
dest
pageNumber
0x08
3.1.4 BOOTLOADER_PAGE_DATA_WRITE
size
source
0x8003
0x00
0x02
0x04
0x06
dest
data: Bytes
0x08
…
6

13. 3.2 Messages from node to bootloader control program
3.2 Messages from node to bootloader control program
3.2.1 BOOTLOADER_DESCRIPTION
6
source
0x8004
0x00
0x02
0x04
0x06
pageSize
pagesStart
pagesCount
0x08
0x0A
3.2.2 BOOTLOADER_PAGE_DATA_READ
size
source
0x8005
0x00
0x02
0x04
0x06
data: Bytes
…
7

14. 3 Messages
3.2.3 BOOTLOADER_ACK
2 (4)
source
0x8006
0x00
0x02
0x04
0x06
errorCode
(errorAddress)
(0x08)
errorCode:
0 Success.
1 Error: Invalid frame size.
2 Error: Programming failed.
3 Error: Not programming.
errorAddress:
Low address of the bytecode where the programming failed (errorCode =2)
8

15. 3.3 Messages from a specific node
3.3 Messages from a specific node
3.3.1 DESCRIPTION
size
source
0x9000
0x00
0x02
0x04
0x06
name: String
protocolVersion
bytecodeSize
stackSize
variablesSize
namedVariableSize
localEventSize
nativeFunctionSize…
9

16. 3 Messages
3.3.2 NAMED_VARIABLE_DESCRIPTION
size
source
0x9001
0x00
0x02
0x04
0x06
size
name: String
…
3.3.3 LOCAL_EVENT_DESCRIPTION
size
source
0x9002
0x00
0x02
0x04
0x06
name: String
description: String
…
10

17. 3.3 Messages from a specific node
3.3.4 NATIVE_FUNCTION_DESCRIPTION
size
source
0x9003
0x00
0x02
0x04
0x06
name: String
description: String
parametersLength
parameter[0].Size
parameter[0].Name: String
…
parameter[n].Size
parameter[n].Name: String
…
3.3.5 DISCONNECTED
0
source
0x9004
0x00
0x02
0x04
11

18. 3 Messages
3.3.6 VARIABLES
size
source
0x9005
0x00
0x02
0x04
0x06
start
variable[0]
…
variable[n]…
3.3.7 ARRAY_ACCESS_OUT_OF_BOUNDS
6
source
0x9006
0x00
0x02
0x04
0x06
pc
size
index
0x08
0x0A
12

19. 3.3 Messages from a specific node
3.3.8 DIVISION_BY_ZERO
2
source
0x9007
0x00
0x02
0x04
0x06
pc
3.3.9 EVENT_EXECUTION_KILLED
2
source
0x9008
0x00
0x02
0x04
0x06
pc
3.3.10 NODE_SPECIFIC_ERROR
4
source
0x9009
0x00
0x02
0x04
0x06
pc
message: String
…
13

20. 3 Messages
3.3.11 EXECUTION_STATE_CHANGED
4
source
0x900A
0x00
0x02
0x04
0x06
pc
flags
0x08
3.3.12 BREAKPOINT_SET_RESULT
4
source
0x900B
0x00
0x02
0x04
0x06
pc
success
0x08
3.4 Message from IDE to all nodes
This section describes messages broadcasted to all robots. There is only
one single messege of this type.
14

21. 3.5 Messages from IDE to a specific node
3.4.1 GET_DESCRIPTION
2
source
0xA000
0x00
0x02
0x04
0x06
version
This message is also known as the “presence” message. It is usually the
first message sent by the IDE to initiate the dialog with the robots.
3.5 Messages from IDE to a specific node
The following messages target a specific robot. The first argument in the
message’s payload is always the id of the robot.
3.5.1 SET_BYTECODE
size
source
0xA001
0x00
0x02
0x04
0x06
dest
start
bytecode[0]
…
bytecode[n]
0x08
0x0A
…
15

22. 3 Messages
3.5.2 RESET
2
source
0xA002
0x00
0x02
0x04
0x06
dest
3.5.3 RUN
2
source
0xA003
0x00
0x02
0x04
0x06
dest
3.5.4 PAUSE
2
source
0xA004
0x00
0x02
0x04
0x06
dest
16

23. 3.5 Messages from IDE to a specific node
3.5.5 STEP
2
source
0xA005
0x00
0x02
0x04
0x06
dest
3.5.6 STOP
2
source
0xA006
0x00
0x02
0x04
0x06
dest
3.5.7 GET_EXECUTION_STATE
2
source
0xA007
0x00
0x02
0x04
0x06
dest
17

24. 3 Messages
3.5.8 BREAKPOINT_SET
4
source
0xA008
0x00
0x02
0x04
0x06
dest
pc
0x08
3.5.9 BREAKPOINT_CLEAR
4
source
0xA009
0x00
0x02
0x04
0x06
dest
pc
0x08
3.5.10 BREAKPOINT_CLEAR_ALL
2
source
0xA00A
0x00
0x02
0x04
0x06
dest
18

25. 3.5 Messages from IDE to a specific node
3.5.11 GET_VARIABLES
6
source
0xA00B
0x00
0x02
0x04
0x06
dest
start
length
0x08
0x0A
3.5.12 SET_VARIABLES
size
source
0xA00C
0x00
0x02
0x04
0x06
dest
start
variable[0]
…
variable[n]
0x08
0x0A
…
19

26. 3 Messages
3.5.13 WRITE_BYTECODE
2
source
0xA00D
0x00
0x02
0x04
0x06
dest
3.5.14 REBOOT
2
source
0xA00E
0x00
0x02
0x04
0x06
dest
3.5.15 SUSPEND_TO_RAM
2
source
0xA00F
0x00
0x02
0x04
0x06
dest
This message sends the robot to sleep.
20

27. 3.5 Messages from IDE to a specific node
3.5.16 INVALID
0
source
0xFFFF
0x00
0x02
0x04
21