Newer
Older
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)
* [License](#license)
# 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](http://microfluidics.utoronto.ca/gitlab/dstat/dstat-firmware/builds) from the automated build system (click the download button for the desired build) and can be uploaded using [avrdude](http://www.nongnu.org/avrdude/) or Atmel Studio.
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
The most up to date [code](http://microfluidics.utoronto.ca/gitlab/dstat/dstat-firmware/repository/archive.zip?ref=develop) 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)
# License
ASF code is subject to the following copyright terms:
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
*Copyright (c) 2012 Atmel Corporation. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. The name of Atmel may not be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* 4. This software may only be redistributed and used in connection with an
* Atmel microcontroller product.
*
* THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
* EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
All other code is licensed under the [GNU Public License](/LICENSE) v3.