Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

SAM-BA Protocol

Sven Köhler

The SAM-BA Protocol

This page describes the protocol used by the SAM-BA bootloader that's built into some Atmel CPUs like the one in the Lego NXT.
It can be used to reprogram the CPUs internal Flash memory for example.

Here is the command structure that I observed by sniffing the communication of the official Atmel SAM-BA software with a serial port monitor. This page already lists some of the commands. However, it contains some minor errors. Also, some details (especially the behaviour of the commands in interactive mode) were determined manually using hterm.

General Rules

The SAM-BA bootloader can be switched between two modes. In the interactive modes, the bootloader replies with a prompt (which consists of the ">" character) after each command.
In the non-interactive mode, it sends no data in addition to the data returned by the individual command.

Each command sent to bootloader has to be terminated with # (0x23) and LF (0x0A).
A line within the response from the devive is always terminated by CRLF (0x0D 0x0A).

The first argument of the command is the address. The seconds argument is either the value of the word/halfword/octet to be written or the length of the data being written or read.

Individual commands

Command Meaning Response (Interactive) Response (Non-interactive)
T switch to interactive mode CRLF + CRLF + prompt CRLF + prompt
N switch to non-interactive mode CRLF, no prompt nothing
V get version string (for example "v1.4 Nov 10 2004 14:49:33") version string + CRLF + prompt version string + CRLF
W<8 hex digits>,<8 hex digits> write word CRLF + prompt nothing
w<8 hex digits>,4 read word hex-number (like "0x1234ABCD") + CRLF + prompt 4 octets
H<8 hex digits>,<4 hex digits> write half word CRLF + prompt nothing
h<8 hex digits>,2 read half word hex-number (like "0x12AB") + CRLF + prompt 2 octets
O<8 hex digits>,<2 hex digits> write octet CRLF + prompt nothing
o<8 hex digits>,1 read octet hex-number (like "0x1A") + CRLF + prompt 1 octet
S<8 hex digits>,<8 hex digits> write lots of data. The data to be written must follow the terminator of the command. CRLF + prompt nothing
R<8 hex digits>,<8 hex digits> read lots of data. CRLF + as many octets as specified be the second parameter + prompt as many octets as specified be the second parameter
G<8 hex digits> Execute code at given address CRLF (before the jump to the given address), no prompt nothing

The w/h/o commands cannot be used to read multiple words/haldwords/octets in a single command. The second argument seems to be ignored, actually. It is not known, whether the G-command supports jumps to thumb code. Presumably, this could be achieved by using an odd address (lowest bit set). In interactive mode, the hex-number returned by the w/h/o commands is derived by interpretating the data at the given address using little-endian. Also the value passed to the W/H/O command is written to memory using little-endian.

Initialization sequence

The initialization sequence used by version 2.8 of the official Atmel SAM-BA software is to first send a T command and wait for the prompt. Then it starts sending an N command followed by the various read/write commands. Newer versions seem to start with a N command right away.

Sending a N command as the first command is problematic. It is unclear, whether the device will send a response or not. Sending a T command is the better strategy, since it is guarantee to send a response. The response is of variable length, but the end is detectable (the prompt).

Sample communication trace

Port opened by process "SAM-BA_cdc.exe" (PID: 1528)
Request:
 4E 23 0A                                          N#.             
Answer:
 0A 0D                                             ..              
Request:
 77 66 66 66 66 66 32 34 30 2C 34 23 0A            wfffff240,4#.   
Answer:
 40 09 0D 27                                       @..'            
Request:
 53 32 30 32 30 30 30 2C 61 35 63 23 0A 20 00 00   S202000,a5c#. ..
 ... 165 * 16 octests data ...
 00 7D 24 20 00 18 47 C0 46 0A 57 32 30 32 30 30   .}$ ..GÀF.W20200
 34 2C 30 23 0A 57 32 30 32 30 30 63 2C 33 23 0A   4,0#.W20200c,3#.
 57 32 30 32 30 31 30 2C 34 23 0A 57 32 30 32 30   W202010,4#.W2020
 31 34 2C 30 23 0A 47 32 30 32 30 30 30 23 0A 77   14,0#.G202000#.w
 32 30 32 30 30 34 2C 34 23 0A                     202004,4#.      
Answer:
 FF FF FF FF                                       ÿÿÿÿ            
Request:
 77 32 30 32 30 30 38 2C 34 23 0A                  w202008,4#.     
Answer:
 00 00 00 00                                       ....            
Request:
 77 32 30 32 30 30 63 2C 34 23 0A                  w20200c,4#.     
Answer:
 00 00 04 00                                       ....            
Request:
 77 32 30 32 30 31 30 2C 34 23 0A                  w202010,4#.     
Answer:
 7C 2B 20 00                                       |+ .            
Request:
 77 32 30 32 30 31 34 2C 34 23 0A                  w202014,4#.     
Answer:
 00 D3 00 00                                       .Ó..            
Request:
 77 32 30 32 30 31 38 2C 34 23 0A                  w202018,4#.     
Answer:
 00 40 10 00                                       .@..            
Request:
 77 32 30 32 30 31 38 2C 34 23 0A                  w202018,4#.     
Answer:
 00 40 10 00                                       .@..            
Request:
 77 32 30 30 30 30 30 2C 34 23 0A                  w200000,4#.     
Answer:
 13 00 00 EA                                       ...ê            
Request:
 77 32 30 30 30 30 34 2C 34 23 0A                  w200004,4#.     
Answer:
 FE FF FF EA                                       þÿÿê            
Request:
 77 32 30 30 30 30 38 2C 34 23 0A                  w200008,4#.     
Answer:
 54 00 00 EA                                       T..ê            
Request:
 77 32 30 30 30 30 63 2C 34 23 0A                  w20000c,4#.     
Answer:
 FE FF FF EA                                       þÿÿê            

... many read requests from 0x200010 to 0x2000ec ...

Request:
 77 32 30 30 30 66 30 2C 34 23 0A                  w2000f0,4#.     
Answer:
 FB FF FF 1A                                       ûÿÿ.            
Request:
 77 32 30 30 30 66 34 2C 34 23 0A                  w2000f4,4#.     
Answer:
 00 00 A0 E3                                       .. ã            
Request:
 77 32 30 30 30 66 38 2C 34 23 0A                  w2000f8,4#.     
Answer:
 50 1D A0 E3                                       P. ã            
Request:
 77 32 30 30 30 66 63 2C 34 23 0A                  w2000fc,4#.     
Answer:
 80 29 A0 E3                                       €) ã            

SAM-BA program is terminated.

Request:
 54 23 0A                                          T#.             
Answer:
 0A 0D 3E                                          ..>             
Port closed

Related

NXT Wiki: Home