|
|
|
This is the documentation for the DStat microcontroller firmware.
|
|
|
|
|
|
|
|
## Table of Contents:
|
|
|
|
|
|
|
|
* [Introduction](#introduction)
|
|
|
|
* [Building from source](#building-from-source)
|
|
|
|
* [Build requirements](#build-requirements)
|
|
|
|
* [Building with Make](#building-with-make)
|
|
|
|
* [Building with Atmel Studio](#building-with-atmel-studio)
|
|
|
|
* [Installation](#installation)
|
|
|
|
* [Requirements](#requirements)
|
|
|
|
* [Fuse bits](#fuse-bits)
|
|
|
|
* [Firmware files](#firmware-files)
|
|
|
|
* [Using Make](#using-make)
|
|
|
|
* [Atmel Studio 6](#atmel-studio-6)
|
|
|
|
* [Connection and testing](#connection-and-testing)
|
|
|
|
* [Mac OS X and Linux](#mac-os-x-and-linux)
|
|
|
|
* [Windows](#windows)
|
|
|
|
|
|
|
|
# Introduction
|
|
|
|
The DStat's operation is controlled by an Atmel XMega microcontroller.
|
|
|
|
Its main functions are to communicate instructions and data with a computer over a USB CDC interface and perform experiments by controlling the onboard peripherals.
|
|
|
|
The software that runs on the microcontroller is known as firmware and is written in plain C using many parts of Atmel's ASF framework.
|
|
|
|
|
|
|
|
# Building from source
|
|
|
|
Precompiled binaries of the firmware are available in the `release` branch, but these may not contain the latest changes to the source.
|
|
|
|
The most up to date code can be found in the `develop` branch and must be compiled before it can be loaded onto the microcontroller.
|
|
|
|
|
|
|
|
## Build requirements
|
|
|
|
|
|
|
|
* Mac or Linux:
|
|
|
|
* GNU Make (OS X: included with Developer Tools)
|
|
|
|
* avr-gcc (OS X: install with homebrew)
|
|
|
|
* avr-libc (OS X: install with homebrew)
|
|
|
|
* Windows:
|
|
|
|
* [Atmel Studio 6](http://www.atmel.com/tools/atmelstudio.aspx)
|
|
|
|
|
|
|
|
## Building with Make
|
|
|
|
|
|
|
|
The easiest way to build the firmware on Mac or Linux (Make is available in Windows, but the Makefiles may need changes to run correctly) is using the included Makefiles:
|
|
|
|
````
|
|
|
|
cd DSTAT/
|
|
|
|
make
|
|
|
|
cd ../EEPROM\ init/
|
|
|
|
make
|
|
|
|
````
|
|
|
|
|
|
|
|
This will produce binary files in the `DSTAT` and `EEPROM init` directories.
|
|
|
|
The files in `DSTAT` are the firmware binaries that will be loaded onto the microcontroller.
|
|
|
|
The `dstat-firmware-eeprom.eep` file in the `EEPROM init` directory is a file to initialize the microcontroller's EEPROM.
|
|
|
|
It should be uploaded once on a new microcontroller, but generally shouldn't need to be done again except to reset settings or if new options that use the EEPROM are added to the firmware.
|
|
|
|
|
|
|
|
## Building with Atmel Studio
|
|
|
|
|
|
|
|
Instructions for building in Atmel Studio 6 can be found [here](http://www.avr-tutorials.com/avr-studio-6/generating-hex-file-avr-studio-6).
|
|
|
|
The solution file is in the main `dstat-firmware` directory.
|
|
|
|
|
|
|
|
# Installation
|
|
|
|
## Requirements
|
|
|
|
To install the firmware onto the DStat's microcontroller, you'll need a programming tool that supports PDI.
|
|
|
|
A simple and inexpensive programmer is [Atmel's AVRISP mkII](http://www.atmel.com/tools/avrispmkii.aspx).
|
|
|
|
In the future, updating the firmware over USB may be supported, but it's not a priority as a programming tool must still be used at least once to bootstrap the microcontroller.
|
|
|
|
|
|
|
|
To load the firmware, you'll need either [Atmel Studio](http://www.atmel.com/tools/atmelstudio.aspx), a full-featured development platform (Windows-only), or [AVRDUDE](http://www.nongnu.org/avrdude/), a cross-platform command line tool.
|
|
|
|
On Mac OS X, AVRDUDE can be installed using [homebrew](http://brew.sh): `brew install avrdude`
|
|
|
|
|
|
|
|
## Fuse bits
|
|
|
|
The XMega has one of the SPI ports we need configured for JTAG use, by default, and needs to be disabled by setting one of the microcontroller's fuse bits.
|
|
|
|
The JTAGEN bit of FUSEBYTE4 should be set to 1.
|
|
|
|
This only needs to be done once per microcontroller.
|
|
|
|
This must be done manually if you're using Atmel Studio, but will be taken care of automatically by the makefile method.
|
|
|
|
This can be done from the [Fuses](http://www.atmel.com/webdoc/atmelstudio/atmelstudio.programmingdialog.fuses.html) page of the Device Programming window—simply uncheck `JTAGEN` and click `Program`
|
|
|
|
|
|
|
|
## Firmware files
|
|
|
|
The memory files used to program the microcontroller are found in the DSTAT and EEPROM init directories:
|
|
|
|
* Firmware: `DSTAT/dstat-firmware.elf`
|
|
|
|
* EEPROM initialization: `EEPROM init/dstat-firmware-eeprom.eep`
|
|
|
|
|
|
|
|
Before programming, make sure your programmer is connected to your computer and its PDI connector is connected to the pin header labelled AVR-PDI on the DStat.
|
|
|
|
The side with the red wire should face the pin labelled 1 on the PCB.
|
|
|
|
|
|
|
|
### Using Make
|
|
|
|
Similar to building from source, the make command can be used to program the microcontroller.
|
|
|
|
By default, the Makefiles are configured to use an AVRISP mkII connected over USB.
|
|
|
|
If you are using a different programmer, be sure to set the `AVRDUDE_PROG` and `AVRDUDE_PORT` options in the `config.mk` files found in the DSTAT and EEPROM init directories.
|
|
|
|
See `man avrdude` for more information about these options.
|
|
|
|
|
|
|
|
To upload the firmware file and set fuse bits:
|
|
|
|
````
|
|
|
|
cd DSTAT/
|
|
|
|
make program
|
|
|
|
````
|
|
|
|
Occasionally, setting the fuse bits may fail.
|
|
|
|
If an error occurs on verification, simply run `make program` again.
|
|
|
|
|
|
|
|
To initialize the EEPROM:
|
|
|
|
To upload the firmware file and set fuse bits:
|
|
|
|
````
|
|
|
|
cd EEPROM\ init/
|
|
|
|
make program
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
|
|
### Atmel Studio 6
|
|
|
|
Follow the directions [here](http://www.atmel.com/webdoc/atmelstudio/atmelstudio.AVRStudio.ProgrammingDialog.Introduction.html) to program the microcontroller.
|
|
|
|
Be sure to select `ATXMEGA256A3U` as the Device and `PDI` as Interface.
|
|
|
|
|
|
|
|
In the Memories tab, `dstat-firmware.elf` should be selected for Flash and `dstat-firmware-eeprom.eep` should be selected for EEPROM.
|
|
|
|
Remember to click the separate Program button for each.
|
|
|
|
|
|
|
|
# Connection and testing
|
|
|
|
If the firmware has been successfully applied, it will be possible to connect to the DStat over USB.
|
|
|
|
|
|
|
|
|
|
|
|
## Mac OS X and Linux
|
|
|
|
Mac OS X and Linux do not require driver files and will automatically enumerate the DStat and give it an entry in /dev/ as a virtual serial port.
|
|
|
|
On OS X, the DStat should appear as `cu.usbmodem12...E1`.
|
|
|
|
On Linux, check the /dev/ directory for new entries after you plug the DStat in.
|
|
|
|
|
|
|
|
Once connected, you can test communications using a terminal emulator (following the communications protocol in `dstat-firmware/communication protocol.txt`):
|
|
|
|
````
|
|
|
|
$ screen /dev/cu.usbmodem12...E1
|
|
|
|
$ c
|
|
|
|
#
|
|
|
|
$ k
|
|
|
|
#INFO: 30k
|
|
|
|
````
|
|
|
|
## Windows
|
|
|
|
Unlike Mac and Linux, Windows does not automatically load its USB CDC driver and needs a wrapper driver installed.
|
|
|
|
The process is similar to installing [Arduino drivers](http://www.arduino.cc/en/guide/windows#toc4), but using the driver file included in the `drivers` directory of `dstat-interface`.
|
|
|
|
Unfortunately, if you are running Windows 8, this requires disabling driver signing enforcement. (thank Microsoft) |
|
|
|
\ No newline at end of file |
