When programming Atmel® AVR microchips, there are several communication protocols available, and it's important to choose the correct one. Adhering to the correct protocol is essential in order for your programmer of choice to understand what you want it to do.
So far, avrgirl has had to support three of these protocols: STK500v1, STK500v2, and AVR109. In this post, we'll go into detail for one of these protocols in particular: STK500v2 and the resulting avrgirl release: avrgirl-stk500v2.
Even though there is already a package available in npm for STK500v2 (thank you Ryan), I thought it would be beneficial to write an alternative version for avrgirl, as I wanted the API to look and work quite different. Not to mention that I was pretty sure I'd learn a lot from the process of writing it from scratch using the datasheet. Read it if you're interested in seeing what kind of resources I work with when developing software for general electronics!
avrgirl-stk500v2 implements a protocol only, but it still works as a standalone package to use with any USB device which speaks STK500v2. This was by design. I tried to keep it as generic as possible.
STK500v2 is quite a verbose protocol compared to others, even STK500v1. Headers and checksums are required even to send a simple request or instruction.
Here is the general communication signature for most instructions:
MESSAGE LENGTH (MSB)
MESSAGE LENGTH (LSB)
Responses from the programmer follow an identical signature.
As the name suggests, this byte signifies the start of a new message. The byte value is the same each and every time - it's
This number needs to be incremented by 1 for each message sent. Once the sequence value reaches 255, it should wrap around back to 0 again.
This tells the programmer how many bytes are in the main message body you're sending. It does not count the header bytes, nor the checksum. We supply the length in both MSB (most significant byte first) and LSB (least significant byte first) formats.
Here is where you put your instructions for the microchip. It could be asking for its signature, writing a fuse, or a number of other things that the microchip supports.
The simplest example of a message body is getting a parameter value from the programmer settings:
0x03, 0x91 - the first byte is the 'get parameter' command, and the second byte is specifically asking for the major version number of the software running on the programmer.
This is a byte that is formed with logical shifts of all of the previous bytes in the message, including the headers. This is how we signify that our message is complete.
There are, as always, exceptions to the rule. Most programmers which use STK500v2 follow the protocol exactly. However, I have found at least one programmer (made by Atmel® themselves, gah) that does not.
The AVRISP mkII, for example, wants to skip both the headers and the checksum at the end. I only found this out through trial and error after some relative frustration. It was technically in the datasheet for the programmer, but I made the wrong assumption that the author had dropped these bytes from each example for the sake of brevity.
As a side effect, this brought in the notion of 'framed' and 'frameless' messages. If a message is framed, the message is wrapped in the headers and the checksum described in the previous section of this post. If it is frameless, only the message body is sent.
The end result that I implemented - requesting frameless mode is an optional parameter in the options object passed into the module when instantiated. The library takes care of the rest.
I decided early on that avrgirl would work with only more modern programmers which use USB for communication. To offer the best support possible, using either serialport or usb packages will work with avrgirl-stk500v2.
avrgirl-stk500v2 is published on npm!
Currently available functionality:
- Enter / leave programming mode
- Read programmer / chip signatures
- Write to EEPROM and Flash memory
- Read from EEPROM and Flash memory
- Erase chip memory
- Read and write fuses
- Get and set parameters
This list isn't every single thing you can do with this protocol (for example, it doesn't currently support reading locks), but the above methods are what you'd most commonly use.
If you'd like to test out avrgirl-stk500v2, please do! So far I have only had the opportunity to test it on two devices - the Arduino Mega, and the AVRISP mkII. I'd love your feedback, and feel free to open an issue if needed.