 |
ALog
v0.3.2
Open-source Arduino-based data logger library, designed for field science
|
|
ALog
v0.3.2
Open-source Arduino-based data logger library, designed for field science
|
The ALog library is a toolkit for open-source data logging designed for the Arduino-based ALog (http://northernwidget.com/alog/), but that will also work with any standard Arduino-Uno or -Mega-based system that is outfitted with a SD card and a DS3231 real-time clock.
This library is optimized to:
If you use the ALog library (and/or data logger) in a publication, please cite:
**Wickert, A. D. (2014), [The ALog: Inexpensive, Open-Source, Automated Data Collection in the Field](http://onlinelibrary.wiley.com/wol1/doi/10.1890/0012-9623-95.2.68/full), Bull. Ecol. Soc. Am., 95(2), 68–78, <doi:10.1890/0012-9623-95.2.68.**>
In addition to the README.md at https://github.com/NorthernWidget/ALog, documentation is available as a combination of the information here and an index of logger functions in both [HTML] and [PDF] format.
\
No-frills, no-pictures, as quick as possible. All the same material is covered in more detail in the **"Complete guide: from the basics onward,"** below; look there if you get stuck
For those already familiar with Arduino and with all of the required software already installed
The following code is an Ardiuno "sketch" that includes the Alog library. It works whether you are using an:
Support for ARM-series Arduino boards is currently under development.
Sensor commands are defined in detail in the extended help, available below (PDF version) and at http://northernwidget.github.io/ALog/classALog.html.
In short, they look like:
where these parameters can be the pin numbers to which the sensors are attached, sensor-specific electrical characteristics (e.g., resistance), calibration values, and quantities that affect how the sensor behaves during its operation.
One example, for a thermistor (a temperature-sensitive resistor), is:
Where the parameters are, in order:
This thermistor example is reiterated and expanded upon in the "Guide for first-time users: from the basics onward", below.
Printed below is the template function designed to guide users about how to add support for additional sensors. You may also look at ALog.cpp and ALog.h for our current examples, and feel free to contact us (info@northernwidget.com) if you have questions about how to properly incorporate new sensors.
If you do add your sensor to our library or make an improvement, we would really appreciate it if you would contact us about including the changes you've made. We have designed the ALog library as a resource for the community, and the more of us who make it better, the bigger and better open-source field instrumentation grows!
float Vout_normalized_analog_example = analogReadOversample(pin, \ ADC_bits) / 1023.;
float Some_variable = Vout_normalized_analog_example * param1 / param2; if (flag){ Some_variable /= 2.; }
/////////////// // SAVE DATA // ///////////////
if (first_log_after_booting_up){ headerfile.print("Some variable [units]"); headerfile.print(","); headerfile.sync(); }
// SD write datafile.print(Some_variable); datafile.print(F(","));
// Echo to serial Serial.print(Some_variable); Serial.print(F(","));
} ```
(This is identical to "LED messages", below in the full guide)
These messages are flashed on the large red LED. Those in bold are those that you may see most commonly.
(This is identical to "Buttons: RESET and LOG", below in the full guide)
There are two buttons on the ALog:
The ALog has been developed by Andy Wickert and Chad Sandell at Northern Widget LLC and the University of Minnesota.
For questions related to the Logger library, please send a message to us at info@northernwidget.com.
Are you new to the ALog, Arduino, and/or C/C++ programming? If so, this page is for you. We'll guide you through the steps to install a first simple program on your ALog data logger, and introduce you to a few concepts along the way.
\
C and C++ are programming languages.Your ALog board should look something like this. It has a lot of components. We'll start to look at them in more detail once you wire the board up.
\ ALog BottleLogger v2.2.0 top photo
The dimensions of the ALog BottleLogger are perfect to slip it into a Nalgene water bottle: these are often easier to find than gasketed boxes, especially if you're in the outdoors (or outdoors shops).
Yes, we use the big, chunky, old-school SD cards, USB ports, and barrel jack connectors. And we love 'em. Why? Have you ever tried to connect cables with mittens in Minnesota-frigid temperatures? Have you ever dropped a micro-SD card (or other object the size of your pinky nail) into a beautiful bed of colorful oak leaves, stand of prairie grasses, or a lake? You'd better hope that your missing item is as big and recognizable as possible. We call it designing for reality.
(An update... while we love the old-school cool of the big USB A-B cable, we\ couldn't help but notice that tons of us were traveling with A-micro-B cables\ thanks to Android phones, but had to make a special effort to remember to bring\ our A-B cables to the field. So we've made a recent (2017) update to the USB\ port in our design.)
The metal connections between the microcontroller (teeny tiny computer) and any external component of the system (e.g., power supply, sensors) are called "pins".
You are not attaching anything directly to the pins on the integrated circuit, obviously; your interface to the ALog data logger will be primarily through the screw terminals (which in turn are discussed immediately below) at the edges of the board. I refer to each screw terminal as a "pin" or "port", or simply as a "screw terminal"; there is no hard-and-fast language for this, except insofar as only those microcontroller pins that are exposed to the outside world via screw terminals are called "ports" in this documentation.
The Alog BottleLogger follows the Arduino Uno convention for pin numbering.
More information on pins can be found towards the end of this document, in the "Pin definitions" section.
Those black things on the sides with screw heads are the "screw terminals". They clamp down on wires to connect peripherals to the ALog BottleLogger, securely. There are several different sets of letters by them. These are:
"Voltage of the common connector": this is raw power from the batteries. Keep it above 3.6V and below 5.5V. Any higher and you fry things; any lower and the system starts shutting down. We usually use:
This is 5V power, supplied by a switchable charge pump. Note that it will be closer to 5.2V if very small voltages are required. It is most often used to power 5V devices.
This is 3.3V power, supplied by a switchable voltage regulator. It powers 3.3V devices and is used as a reference (and often a power source) for analog measurements.
This is ground. Circuits that start at VCC end here. Don't touch power directly to ground unless you want to destroy something. It is the same as 0V.
These are the analog pins. They measure input voltages in a range between 0 and 3.3 volts. What happened to 4 and 5? They are talking to the real-time clock, and are labeled SDA and SCL on the board.
All analog pins can be used as digital pins as well!
When writing code, the analog pins can be referred to as A0, A1, A2, A3, A6, or A7 safely in all cases.
*Additional <info:*>
The analog pins can be referred to by their base numeral (for the ALog BottleLogger, 0, 1, 2, 3, 6, or 7) in the AnalogRead(analogPinNumber) command that we'll see below; this is the legacy of early versions of Arduino. They must be elsewhere referred to as A0, A1, A2, A3, A6, or A7.
A bit of advanced knowledge: "A0" maps to "14", "A1" maps to 15, and so forth until A7 maps to 21; this is because there are 14 digital pins (0-14), so the analog numbers come right after these. Therefore, while I find A0...A7 easier to remember, you may prefer to use the numbers >13, which is equally valid.
These pins can read or write TRUE or FALSE values. For writing, TRUE means full power (VCC) is delivered. False means the pin goes to GND. Reading values with these pins tells you whether the observed voltage is closer to VCC or to GND.
When programming these pins, refer to them by their number alone, dropping the D (and anything after the number that immediately follows the D.
This pin can be used as an interrupt, to observe an event. We often use it with anemometers (spin counters) and tipping-bucket rain gauges.
When programming with this pin as an interrupt, use the following syntax:\ attachInterrupt(digitalPinToInterrupt(3), ...)
If you insert the interrupt number (1), this will correspond to Pin 3 on the Arduino Uno or Alog BottleLogger, but will refer to Pin 1 on ARM-based devices, so this will cause compatibility problems.
Pulse-width modulation. Actually, this isn't written on the board. It uses the analogWrite() function in Arduino and simulates a voltage between GND (0V) and VCC by turning itself on and off very quickly, repeatedly.
Receive and transmit: these are your serial pins. Be careful: they are also attached to the USB port (to talk to your computer), so they must be shared. For the electronics-savvy: they are connected to the computer via 1 kΩ in-series resistors, so external sensors will override USB communications. See "UART", below.
These are the pins for the SPI communications protocol. This protocol is used to communicate with the SD card. You may also use it with some external sensors. See section "SPI", below.
These are the pins used for the I2C communications protocol. This works with the real-time clock, and can connect to external peripherals as well. For the tech-heads: we are updating the design to optimize this for 3.3V design, common among I2C devices. See section "I2C", below.
The ALog BottleLogger has several pins that are used for dedicated functions. These are:
In addition, there are three significant digital interfaces that have uses internal to the ALog but that may also be used to communicate with external sensors:
The UART, or universal asynchronous receiver–transmitter, communicates to the computer via a USB–serial converter (model number FT231X). It transmits these signals through in-series 1 kΩ resistors that act to limit the current that passes in this signal, with the goal of allowing external sensors that communicate via the UART to take precedence over USB–serial communications to the computer. While this is available and functions, we recommend against its use as there will almost certainly be some amount of interference between the communications with the computer and with the sensor. In-development versions of ALog boards will have multiple UART ports, and these will include a dedicated port for communication with the computer and other UART ports for use with sensors.
SPI is a 4-wire communication protocol (i.e., bus): three wires/pins are shared between all SPI devices, while a fourth one is used as a "chip select" pin that is set LOW for communication with the logger and HIGH when all communications should be ignored.
It is straightforward to extend SPI to other devices by configuring one of the pins on the ALog data logger to be the new "chip select" pin. In addition to this, the pins with a set configuration are:
The abbreviations stand for "Master out, slave in", "master in, slave out", and "serial clock". I'm really not OK using the term "slave" for about a million reasons, so whenever I need to refer to the device attached to the logger, I will write "agent" or "external device". This goes for any bus – not just SPI.
Additional information on SPI and setting up additional SPI devices may be found at:https://www.arduino.cc/en/reference/SPI.
I2C is a 2-wire communications protocol. It is used to communicate with the real-time-clock (RTC, model number DS3231), as well as many sensors. Each attached device has its own address, enabling up to 128 sensors to be attached to the same I2C port as the clock. But just be careful that your sensor code is good – if it is not and halts the I2C system, it could affect the clock and therefore the entirety of the operations of the ALog!
The pair of plastic vertical "headers" – things with holes in them for wires – are for reference resistors to read analog resistance-based sensors. A simple example is a thermistor, and we'll cover that farther on down here. For now, just consider these resistors to be standards against which many analog sensors will be compared to measure their resistance values.
There are two buttons on the ALog:
The Arduino IDE (Integrated Development Environment) is the current programming environment we use to write and upload programs to the ALog. (Other options exist, but this is the most beginner-friendly.) We haven't yet tested the brand-new web editor, so we'll be suggesting an old-fashioned download. And if you're deploying these in the field, you'll need the downloaded version! Go to https://www.arduino.cc/en/Main/Software. Get it, install it, go.
The ALog boards are "third-party" Arduino boards, so you'll have to set up support for these boards yourself. We've made a pretty thorough walkthrough that you can view here at https://github.com/NorthernWidget/Arduino_Boards, and have included those installation instructions here, immediately below.
Each board will be added as an entry to the Arduino Tools > Board menu.
Go to File > Preferences (or Arduino > Preferences on Mac).
\ preferences"
Open the Arduino IDE preferences
Open 'Additional Boards Manager URLs', and paste the following in either the box for Additional Boards Manager URLs, or, if this is populated, the window that pops up when you hit the button to the right of the Additional Boards Manager URLs text entry area:
https://raw.githubusercontent.com/NorthernWidget/Arduino_Boards/master/package_NorthernWidget_index.json
\ Paste the URL here.
\ Unless you already have done that for third-party boards... in that case, open this frame and paste the URL here.
Now, go to Tools > Board > Boards Manager....
Click it, and the following window will appear:
\ Boards Manager.
if you type in "Northern Widget" (or usually just "Northern" as well), you should see an option to install board files for Northern Widget Arduino compatible boards.
\ Northern Widget boards.
If Northern Widget options do not appear. restart your Arduino IDE and try again.
Click "Install" to add the NorthernWidget boards to your list. At the time of writing, we support only AVR boards, but this may change soon.
\ ALog (AVR) support installed.
Now, when you select the Boards list, you will see a collection of new boards for Northern Widget.
You will then want to change your chosen board to the board that you have. At the time of writing, this is probably the "ALog BottleLogger v2"; the "legacy" option is used for v2.0.0-beta and prior, and there are fewer of these boards in circulation.
\ Select the proper board.
That's it! You're done, and ready to rock and roll... er, collect data, with your ALog data logger.
The ALog also relies on some custom software libraries. These are collections of computer code that help make everything from running basic data logging utilities to interfacing with specific sensors easier. We're introducing you to these libraries up here, even though they won't be needed until quite a bit further down. While we highly recommend them and they are very helpful for field work, you can also program the ALog without them! In fact, the earlier examples (below) do not include the custom libraries.
Currently not recommended, at least until all components can be downloaded this way
Stable versions, but outdated during times of rapid development
The Arduino IDE has a library manager! Here we will walk you through how to use it to obtain and install the requisite libraries. This uses the graphical interface, but can take longer than, "Option 2", below.
At the moment, you will also have to download the stable release (below) and copy the SFE_BMP180 library into your "Arduino/libraries" folder; we're working to streamline this.
First, open the libraries manager.
\ "libraries"
Then, look up each of the three core libraries:
DS3231 (real-time clock):
\ SdFat (SD card):
\ ALog (all data logging!):
\ Once this is done, go to the instructions for Option 2 (immediately below) to get the SFE_BMP180 library.
Not automated in the IDE but much simpler!
Stable release: [ZIP] [TAR.GZ] (recommended)
Nightly build: [ZIP] [TAR.GZ] (for only those who can tolerate things breaking once in a while)
Unzip the archive, and place the contents in your "**Arduino/libraries**" folder. This should be in your home directory or your Documents. Then restart the Arduino IDE (if it is open).
If you're not a programmer (yet!), you might be thinking, "yeah, right, I can't program."
But we say, **"Yeah, right! You can program!"** We'll walk you through it:
*[For the folks already in the know: the Arduino programming language is variant of C/C++.]*
These are serious good. You can follow along with them! https://learn.adafruit.com/series/learn-arduino If you follow them, note that the ALog BottleLogger can take only 3.6 – 5.5 volts, and that the LED is controlled by Pin 8 (not 13). Here is their version of the "blink" example that we'll do below. https://learn.adafruit.com/adafruit-arduino-lesson-1-blink?view=all Look at as many of these as you want! Yes, your ALog can:
Yes, there is a manual! The full reference guide to programming Arduino devices is here https://www.arduino.cc/en/Reference/HomePage.
We're not kidding. We type things into our favorite search engine when we can't figure them out and/or are too tired to think. 90+% of the time, this gets us to the right answer. Sometimes it takes longer than others. Arduino forums and StackExchange are pretty great: Arduino forums Arduino stack exchange [stack exchange is just about the most effective way of conveying the right answers for how to do things that I've (Andy has, that is!) ever seen on the internet]
Programming languages all have ways in which logical thoughts are placed into text that is entered into a computer. Here is a non-exhaustive list of these. It is not intended to be complete, but to give you some essential tools to start reading the code that appears below.
Each variable needs to be defined before it is used.
Each of these goes: variable_type variable_name = variable_value ; For more information on types, see the Sparkfun Electronics tutorial at https://learn.sparkfun.com/tutorials/data-types-in-arduino. For what you are doing right now, a general idea of what these definitions are and what they look like should work.
Ignore lines that start with:
And lines that are between
These are for the benefit of the humans reading the code. Comment your code clearly and thoroughly!
Lines must be terminated with semicolons.
Basic arithmetic operators (+, -, *, /) work. Division of two integers results in "floor division, or rounding down the result. There are also logical operators (<, >, ==, etc.)
These are ways to control the flow of a code. I'm afraid that this introduction to the ALog would be diluted by the details of these. I point the interested reader to the main Arduino reference: https://www.arduino.cc/en/Reference/HomePage.
Use a USB cable to connect the ALog to your computer. (Photo from ALog v2.0.0; v2.2.0+ use microUSB, like Android cell phones.)
\ Then, using the Arduino IDE, select the name of the USB-serial port that is connected to the ALog.
\ Now your ALog is ready for communications and programming.
Arduino programs, often called "sketches", are how you tell the ALog data logger what to do. Here is some information to get you started.
If you open a new Arduino program, it will look like this:
setup() and loop() are both functions. These are specific sets of code that are executed when their names are called in the code. These two functions are special in that:
setup() is run once, when the data logger starts runningloop() is run continuously, after setup().Before these functions, you can place all of your variable definitions.
Once your code is written – either as a copy/paste of this or as your own – save your code. All Arduino sketches need to be within their own folder. After this, you can hit the "upload" button (right arrow) to load the code to the board. (The check mark to the left will test if your code compiles.)
\
Let's make a blinky light turn on and off! On the ALog, pin 8 is attached to a red indicator LED. Here is some code to create a syncopated blinky light.
Look at the comments in the code for information on what each of the commands do; these are detailed more below in the USB/Serial communications section.
A second important piece of your work with the Arduino is to communicate with it. We'll start with one-way communications, with the ALog talking to your computer. We will still flash the LED, and will add in information on how to define a variable outside of these two functions. The comments give you some general idea of what each section does; I will break down the importance of each section below.
Before running this code, open the serial monitor and change your baud rate to 38400 bps!
\ (Note that if I would have clicked, an error message would have popped up below saying that it cannot find a device at the given port: this is because I have no board plugged in. If you get this message and do have a board plugged in, go to Tools > Port > **[new port that you pick]**)
\
Let's break this down a little bit:
Here we are defining the pin number that controls the LED. This is Pin 8, which is a digital pin; analog pins would generally have an "A" before their pin number, and can also be used for digital input and output.
"**Serial**" is a library for USB-Serial communications between the computer and the attached Arduino. It is a core part of Arduino, and therefore does not have to be "included" at the top in the way the ALog library (farther below) must be. To view serial communications, you may open the serial monitor in the Arduino IDE (the figures immediately above describe how to do this).
Within the Serial.begin() command, we set the baud rate to "38400"; this is in bits per second. Technical note: We choose this rate because it is closer to being integer-divisible by our 8 MHz processor clock speed than other baud rates are.
the pinMode command can be set to input or output; "input" means that the pin is ready to read an incoming signal; output means that it maximizes the amount of electrical current it can source to send a strong output signal that is also enough (40 mA absolute maximum) to power basic devices.
Serial.println prints the requested text and then moves ahead to a new line for the next print command (if any).
delay takes an argument in milliseconds that describes how long you would like the logger to do nothing but count time passing.
digitalWrite turns an output pin ON (HIGH) or OFF (LOW). When HIGH, the pin is sending current at a voltage corresponding to VCC (i.e., the positive voltage for the system). When low, it is sending current at a voltage corresponding to GND (ground / Earth).
The full reference to the ALog library is located at\ http://northernwidget.github.io/ALog/classALog.html.
The following sections walk you through the functionality.
The ALog library contains:
The end user can instantiate the ALog class, that is, create one's own version of it for a particular purpose, as follows:
Here, "ALog" is the class, and "alog" is one's instance of the class. It's a bit like picking out a Lego set from a store: it becomes yours, and you can build what you like with it, within the constraints of the pieces that you have.
You may call any function within the ALog class by typing alog.<function_name>(<parameters_to_pass>).
The utility code is the unseen backbone of the ALog library, and much of the reason that I wrote it in the first place. It handles power consumption, device stability, communications with the user, real-time clock management, and reading and writing files to and from the SD card.
The sleep mode is the most important piece of the ALog data logger. It's the superlative of when you close the lid of a laptop computer: the ALog goes from drawing at least 6.7 milliamps to just 53 microamps – that's 0.053 milliamps, for a greater than 100x increase in power efficiency, and therefore battery life.
The internal sleep functions are activated by the end-user as part of this command:
alog.goToSleep_if_needed(); // Send logger to sleep
When the logger wakes up, it takes readings and then goes back to sleep. How does it wake up? There are two ways:
The logger can also be run in a mode to maximize logging speed (around 10 Hz at top speed, but not well-measured at the time of writing) and never sleep!
The real-time clock maintains the absolute time to within ±0.432 s/day. It also operates two alarms, which can be used to trigger the ALog.
As a safety feature, we enable the second of these alarms to go off several after the first one is triggered at the user-specified time. If the first alarm goes off, the second is disabled and advanced farther into the future. Otherwise, if the first alarm doesn't go off, the second alarm is triggered and the logger advances both alarms to the next logging interval. It also records the time at which the failure of the first alarm took place. Thus far, I have never seen this in use outside of test cases in which we force the first alarm to fail.
Interfacing with the real-time-clock is performed through the DS3231 library, which is a combination of RTClib (a standard real-time clock library by J.-C. Wippler) and code to run the DS3231 written by E. Ayars and edited by A. Wickert.
All times are represented as a UNIX Epoch, seconds since January 1st, 1970. This is a very widespread format with plenty of converters into conventional date/time, and solves the problems of (a) storage of date/time data into a complex data type on a small system, and (b) daylight savings time and leap years.
Utilities to read and write to and from the SD card are managed via the SdFat library, by Bill Greiman. The ALog will write to the following files, in rough order of how common their use is:
Always included:
Sometimes included:
TruePower to the SD card is cut between logging intervals to conserve energy. This is one reason why we do not use the built-in Arduino SD library, which cannot handle losing power to the SD card (or at least could not back when I first tried, in 2011!)
The watchdog timer will automatically reboot the ALog data logger if it stalls out while logging for more than 8 seconds. This can help to recover from any software errors, as well as any unforeseen circumstances arising in the field (e.g., jostled while logging causing a disruption of some connections). This can really save the day!
These messages are flashed on the large red LED. Those in bold are those that you may see most commonly.
The EEPROM of an ALog data logger or other Arduino-based device is the memory that remains unchanged even if it is reprogrammed. It holds important identifying and calibration information about the ALog data logger.
These can be read by the functions:
You can use these functions with sensors by passing the results from a call to get_3V3_measured_voltage() or get_5V_measured_voltage() to functions as Vsupply or Vref, these being the supply an reference voltages for the sensors, respectively.
The full index of the sensor functions, along with ways to use them, is here:\ http://northernwidget.github.io/ALog/classALog.html
See the thermistor example (below) and the information in the "Basic Reference" (above) for a more in-depth description of how to create and use sensor functions.
Thus far, we have explored many different aspects of the ALog bottle logger. Now, let's bring many of these together in an example of source code for the ALog. In this example, we will measure a temperature-sensitive resistor, or "thermistor", using the analog measurement capabilities of the ALog. This is one of the most basic measurements that one can make with the ALog, but also one of the most important and most commonly employed.
It's time to break this down into its component steps:
The #include call tells the sketch to use the ALog library.
The second line of source code creates an instance of the ALog object, called "alog". We will use "alog" as our portal into all of the tools that the ALog library offers.
// Note: Serial baud rate is set to 38400 bps
Self-explanatory!
dataLoggerName is an identifier for the logger. I typically make it relate to the field site, the task of the logger, and a code number.
fileName is the name of the main data file to be logged to the SD card. (See SD card section, above, for information on all of the files that may be written to the SD card.) This is noted to be in 8.3 format, but doesn't strictly have to be following updates to the SdFat library.
Log_Interval_Seconds, Log_Interval_Minutes, and Log_Interval_Hours all determine how often the logger will record data. Data recording is set to always occur on hours/minutes/seconds that are synchronous across all devices and are set to be referenced as much as possible to a the start of an hour/day/minute (more details in source code).
external_interrupt is true if a device that triggers an instant response is attached, and false if it is not. As noted, this is most commonly a tipping-bucket rain gauge, but it could really be any sensor. The appropriate sensor functions will define the response to the interrupt; the simplest case (rain gauge) is that a time-stamp is recorded to a specific file.
This is the start of the setup() step, which is run once when the logger turns on. Here, the variables from the previous section are passed to the "alog" object instance, which then creates the appropriate variables and their derivatives within the object. This initializes the object and prepares it for logging.
As is written in the comments, set these values for the indicator LED, SDpowerPin, and RTCpowerPin. The latter two are typically unset on non-ALog Arduino boards, and are equal to each other (but already set within the ALog library) for ALog boards.
At this point, the logger has all the information it needs from you, and completes its internal setup.
This is the start of the loop, which repeats infinitely unless the ALog data logger is shut off or fails.
Here, the comments are self-explanatory, mostly; a couple extra explanations:
This is it, where the magic happens!
alog.sensorPowerOn() and alog.sensorPowerOff() turn the voltage regulators that power external sensors on and off, respectively – just like it says in the comments!
logger.thermistorB(...) is the command. The parameters passed, in order, are:
Do you want to know more about these parameters? Look up the function-specific help, which is below if you are looking at the PDF version of the help (downloadable from http://northernwidget.github.io/ALog/ALogReferenceManual.pdf) and available online at http://northernwidget.github.io/ALog/classALog.html.
We don't have any of these here, but examples would be sensors with their own power-supplies, and/or (not consistent with the comment above) sensors that are powered directly via the ALog BottleLogger's VCC. This is not included in the comment because it is generally not how we run sensors – we like to be able to switch them off to conserve power!
As it says: if you think you're in danger of overflowing the buffer, run this command! You'll need 512 characters in your line for this to happen though, and I've never approached this in my work. But hey, someone might!
As it says, the alog.endLogging() command finalizes everything before sending the logger back to sleep. And that's really all there is to it! Your first ALog Arduino sketch in a nutshell.
And as always, if anything here is unclear, please contact us and we'll try our best to fix it – specific advice appreciated!
Coming soon!
The ALog's clock is a key component – without it, all the data are sitting in an unreferenced time frame. This is why we have chosen the DS3231 real-time clock, which has the highest accuracy and stability of any commonly-available real-time clock that does not incorporate an absolute time reference (e.g., with GPS). GPS would be great for some circumstances, and we're developing a logger with it, but this would not be the extreme low-power device that the ALog BottleLogger is.
Enough with the background – how do you set the clock?
You will need the ALog library and the DS3231 library, both of which you should already have at this point, as well as the ALogTalk repository of Python scripts at github.com/NorthernWidget/ALogTalk. In order to run the Python scripts, you need either Python 2 (including pyserial) or for us to have made an executable version for your platform.
When you upload the ALog code to your ALog data logger or Arduino board, it includes code to set the clock via serial communications. Plug in your data logger, run ALogClockSet.py (which is in the ALogTalk repository), and it should work – if it doesn't, hit the reset button.
How do you run ALogClockSet.py?
All operating systems: Open a terminal, navigate to the directory that holds ALogClockSet.py (the directory should be called ALogTalk, and type:
python ALogClockSet.py
Don't have Python? You probably will have figured it out when that failed Here are your options:
Open the "ALog\_DS3231\_set\_echo" example (File (Arduino on Mac) > Examples > DS3231 > ALog_DS3231_set_echo) and upload it to the board.
Open a terminal, navigate to the ALogTalk directory, and type:
python SimpleClockSet.py
\
User's layout and connection guide
[PDF of User's Layout guide]\ (backup link)
This list includes only those pins on the ALog BottleLogger with which the user can connect.
Pin number (Arduino) Label on ALog BottleLogger Capabilities
0 Rx UART Rx* 1 Tx UART Tx* 3 D3/INT1 External interrupt; digital I/O 6 D6 PWM**; digital I/O 9 D9 PWM**; digital I/O 11 MOSI SPI MOSI 12 MISO SPI MISO 13 SCK SPI SCK A0 (14) A0 Analog input (10-bit); digital I/O A1 (15) A1 Analog input (10-bit); digital I/O A2 (16) A2 Analog input (10-bit); digital I/O A3 (17) A3 Analog input (10-bit); digital I/O A4 (18) / SDA SDA I2C SDA A5 (19) / SCL SCL I2C SCL A6 (20) A6 Analog input (10-bit); digital I/O A7 (21) A7 Analog input (10-bit); digital I/O
*The UART is connected to the USB-Serial converter; using it with sensors is possible, but requires caution when designing new UART sensor interfaces to avoid interference with communications with the computer.
**PWM = "Pulse-width modulation"
This table does not include pin capabilities that are technically possible but not recommended. These include:
Label on ALog BottleLogger Connected to...
GND Ground (Earth / 0V / battery negative (-) terminal) 3V3 3.3V ±1% precision low-dropout voltage regulator 5V 5V charge pump; 5V is nominal: for tiny loads, it can go up to 5.2V VCC "Voltage of the common connector" (Power / battery (+) terminal)
Tools/materials needed:
Also helpful:
To be safe, disconnect power from the logger before attaching or detaching any wires. For full disclosure, though, we do this with power attached all the time – this just opens the possibility of something going wrong, and requires steady hands.
Using the screwdriver, open the screw terminal (lefty loosey), stick the end of the wire into it, and then close the screw terminal until you feel significant resistance (righty tighty!). The goal is that the wire can't come out under reasonable force.
\
Two parallel rows of headers are designed to hold through-hole resistors that span one row to the other. Each of these is numbered to correspond to a particular analog port. Why are these here?
The analog channels on the ALog (or any electronic device) read voltage. But a lot of sensors return resistance. So how do we change that resistance into a voltage?
The key is a little bit of circuit algebra for something called the "Voltage divider":
\
For the ALog, the sensor typically lies between 3V3 (a power source, Vin on the above diagram) and an analog pin (Vout on the above diagram). Applying Ohm's law gives you the following equation that one can use to solve for the value of R1 if you know R2.
\
And this is where the reference resistor comes in: this is the R2, connected between Vout and GND.
It is possible, and necessary with a few sensors, to flip the structure around; in this case, a reference resistor is not attached to the header on the board, but is instead attached to the screw terminals for a power source and the appropriate analog port. Such a reversed order may require a flag to be set in the code.
And that's it: the reference resistor is a standard required to measure another unknown resistance, and it is implemented in a circuit that converts the unknown resistance into a voltage.
For more information, see Wikipedia: Voltage divider
This is the last section in the connection guide because it is the one that – hopefully – you will never have to use!
Place your ALog BottleLogger in front of you with the SD card to the right. Look at the upper left corner. Do you see those six holes? Those are the ones that we are talking about. They allow the user to burn programs directly onto the logger. This is called the "In-System Programmer" or "ISP" header.
*(If you are using a standard Arduino, there should be an ISP header as well; if you are using an ARM-based chip, there is a bigger header with smaller pin spacings.)*
When your ALog (or Arduino) arrives, it has a bootloader on it – a small program that allows you to upload code via the USB connection. Useful! But if somehow something happens to the bootloader, you will have to burn a new one. You will need an in-system programmer: AVR ISP, another Arduino, the Adafruit USBtinyISP, etc... there are many possibilities! If you have an ARM-based chip, you will need an ATmel AVR Dragon or other more advanced programming chip.
Then, remove the SD card. The ISP on any standard Arduino uses the SPI interface. The SD card, which also uses the SPI interface, may interfere with bootloader burning.
After this, go to the Tools menu. Make sure that you have selected the proper board (Tools > Board) and programmer (Tools > Programmer: "\[NAME OF YOUR CURRENTLY-SELECTED PROGRAMMER\]"). Then plug the ISP of your choice into the ISP header: simply holding a 6-pin header at an angle in the holes so the metal makes contact is enough for the ALog BottleLogger, but you may solder it if you choose. Once you have a good connection, go to Tools > Burn Bootloader and wait for the programmer to tell you that it has successfully completed the task.
If it doesn't work, the most common reason is because you have inserted the ISP backwards. Flip the ISP header around and try again.
Insert the SD card carefully, and make sure that it is seated! The logger will reset constantly if it is not and it is v2.2.0+. Otherwise, it is important to hit the "RESET" button and make sure that the LOOOOONG-short-short flash pattern occurs. This means that the logger is ready to go. Otherwise, no data will be recorded!
\
In the field, the main way to power the ALog data logger is by plugging in a barrel jack connected to a battery pack. We typically use barrel jacks with screw terminals to attach to generic battery packs (D or AA) that have wire leads; we sometimes use barrel jacks that are already part of the cable.
\
Next to the barrel jack is a solder pad for a JST connector. This may be populated (i.e., you may solder a JST connector to the board here) if needed to attach power supplies.
We typically use 3xD or 3xAA primary cell batteries, as they are light, inexpensive, reliable, and available around the world.
Solar charging system development is ongoing, and once complete, will allow long-term power supply and a higher rate of logger power consumption.
\ ALog in a box. Note that here, the ALog is powered through its VCC and GND screw terminals; this demonstrates a non-standard but acceptable way of supplying power to the logger, and one that works well in a small enclosure like this one.
The last step is deployment! You have to think about how you will mount the logger box:
\ It also is important to consider how you will attach it: do you need:
There are so many ways to mount the loggers in the field that we can't cover all usage scenarios. But here are some important points:
So long, and good luck!
1.8.13
