SparkFun gator:log Hookup Guide

Pages
Contributors: santaimpersonator, Englandsaurus
Favorited Favorite 1

Introduction

Note: The gator:log will NOT function properly when used with the original gator:bit. Users should use the updated gator:bit (v2) with the gator:log for it to operate properly.

Most of you probably have done a science experiment that required data of some sort to be recorded...

SparkFun gator:log - micro:bit Accessory Board

SparkFun gator:log - micro:bit Accessory Board

DEV-15270
$13.95

The gator:log is the perfect data logging tool for your next experiment. With the automation of the data collection process, gone are the days of rushing around with a pen and composition notebook to simultaneously record data and your observations. Now, you only need to sit back and observe your experiment (or just wait for it to complete, if no observations are necessary).

The gator:log allows a student(s) to focus more on the experiment than watching a thermometer or sensor readout. Additionally, the micro:bit can still be used to provide a graphical display for observing changes in data, when a sensor readout is required. If tied in conjunction with the gator:RTC, stop watches on time based experiments can become a thing of the past too (with the added benefit of more accurate timing results)!

This tutorial will show you how to get started using this gator:log with the gator:bit (v2) in the micro:bit development environment.

Required Materials

Note: The gator:log will NOT function properly when used with the original gator:bit. Users should use the updated gator:bit (v2) with the gator:log for it to operate properly.

To get started, you'll need a micro:bit to control everything. Each of the products below includes a micro:bit, but the kit and bundle also include some additional accessories that you may want as well.

micro:bit Board

DEV-14208
10 Retired

micro:bit Go Bundle

DEV-14336
18 Retired

SparkFun Inventor's Kit for micro:bit

KIT-15228
2 Retired

To easily use the gator board ecosystem, a gator:bit (v2) will help breakout the necessary pins and you will also need alligator and/or banana cables to connect the gator:bit to the gator:log.

Alligator Test Leads - Multicolored (10 Pack)

Alligator Test Leads - Multicolored (10 Pack)

PRT-12978
$3.50
4
SparkFun gator:bit v2.0 - micro:bit Carrier Board

SparkFun gator:bit v2.0 - micro:bit Carrier Board

DEV-15162
$21.50
2
Banana to Banana Cable - Right Angle

Banana to Banana Cable - Right Angle

CAB-15368
$4.95 $4.46
1

(*These banana cables have a special diameter on the attachment points designed specifically for use with the micro:bit ecosystem. They may or may not be compatible with the banana cables used on your test equipment.)

Additionally, users will also need a µSD card and a µSD USB reader:

microSD USB Reader

microSD USB Reader

COM-13004
$5.50
12
microSD Card with Adapter - 32GB (Class 10)

microSD Card with Adapter - 32GB (Class 10)

COM-14832
$26.95
1
microSD Card - 1GB (Class 4)

microSD Card - 1GB (Class 4)

COM-15107
$5.50

microSD Card with Adapter - 16GB (Class 10)

COM-13833
6 Retired

You may already have some of these materials, so feel free to modify your cart as necessary.

Suggested Reading

The gator:log is pretty straight forward to use in application. However, you may find the following concepts useful along the way.

Serial Communication

Asynchronous serial communication concepts: packets, signal levels, baud rates, UARTs and more!

Serial Terminal Basics

This tutorial will show you how to communicate with your serial devices using a variety of terminal emulator applications.

OpenLog Hookup Guide

An introduction to working with the OpenLog data logger.

SparkFun gator:RTC Hookup Guide

The gator:RTC is an I2C based, real-time clock (RTC) for keeping time while your micro:bit isn't powered. This tutorial will get you started using the gator:RTC with the micro:bit platform.

If you aren't familiar with the micro:bit, we recommend reading here for an overview.

We would also recommend taking a look at the following tutorials if you aren't familiar with them.

Getting Started with the micro:bit

The BBC micro:bit is a compact, powerful programming tool that requires no software installation. Read on to learn how to use it YOUR way!

How to Load MicroPython on a Microcontroller Board

This tutorial will show you how to load the MicroPython interpreter onto a variety of development boards.

SparkFun gator:bit v2 Hookup Guide

The gator:bit v2 is a breakout board for the BBC micro:bit. The gator:bit exposes almost every pin on the micro:bit to clippable pad with circuit protection. It also has as built-in addressable LEDs and a built-in buzzer.

Hardware Overview

The gator:log consists of 5 pads for power, data, and an interrupt.

Contacts Direction Description
GND N/A Ground: Reference voltage and ground loop.
3.3V In Power: Provides 3.3V to the board.
RX In Data and commands are transmitted to the gator:log from an external microcontroller (i.e. micro:bit).
TX Out Data can be read from an SD card on the gator:log by an external microcontroller (i.e. micro:bit).
RST In Pin goes high or low based on if the gator:log needs to be initialized.

Power

The specified operating voltage for the ATmega328 is between 1.8V - 5.5V. For use with the gator:bit (v2) and micro:bit, you should provide 3.3V through the 3V3 and GND pads to keep the logic levels consistent.

Power Connections
Power connection pads.

ATmega328P

The heart of the gator:log is an ATmega328P microcontroller. The ATmega328P is used to handle the incoming data and store it on an µSD card. It is also used to handle all the file directory, organization functions available for the gator:log. For the most part, users just need to be aware that the RST pad must be connected in addition to the other pads.

ATmega328P
ATmega328P microcontroller.

Here are some of the characteristics of the ATmega328P microcontroller from the datasheet:

Characteristic Range
Operating Voltage 1.8V to 5.5V
Current Idle: approx. 25 mA (avg.)
Peak: approx. 35mA (w/ status LEDs flashing)
Storage SD Card
Input Channels 1- Serial Data
Speed Input: Serial Data
Output: Serial Data

Reset Pad

The reset pad is used to initialize the begin function for the ATmega328P microcontroller. This pin must be connected when the gator:log is initialized to function properly.

Reset Pad
Reset pad.

What is a Data Logger?

A data logger is a device that records data over time, usually from an instrument or sensor. Most often, they are low power, use a microprocessor, include (internal or external) data storage options, contained in a compact enclosure, and are battery powered. Generally, data loggers are useful for collecting data from remote locations for extended periods of time. In s, these devices will include a renewable power source for self sufficiency and may have a remote data link when it is not be feasible to constantly drive out to change batteries and/or data storage.

Below is a list of a few examples of data logging applications:

  • Weather Stations and Buoys
  • Monitoring Agricultural Conditions
  • Road Traffic
  • Wildlife Conservation
  • Building Monitors (i.e. for Power/Water usage and HVAC Efficiency)
  • Monitoring for Athletes Performance (Biosenors)

For more details on data logging applications, check out these online resources:

µSD Card Slot

A µSD (micro SD) card slot is available to for a µSD card, which is needed to store the data sent to the gator:log. The gator:log uses the SPI pins of the ATmega328P to send data to the SD card from a temporary buffer. In most cases, users only need to consider the recording time of the gator:log, know that the µSD card requires proper formatting, and be aware of the restrictions on the SD cards that are compatible with the gator:log, which are laid out in the table below.

SD Card Slot
Spring loaded µSD card slot.

Characteristic Range
Style µSD card (microSD)
Type SD (SDSC)
SDHC
Class ≥4
Capacity 64MB to 32GB
Format FAT16 or FAT32

Although, many users may already have a few SD cards lying around, the characteristics laid out in the table are known to be compatible with the gator:log. Be aware that using SD cards that fall outside of these restrictions are not guaranteed to work. If you aren't sure about the style or type of SD card you have, please check out this Wikipedia article on SD cards for more details.

Spring-Loaded Locking Mechanism: Once the SD card is placed in the slot, push in the card once. You should hear a soft click when the card is locked into place. To unlock or release the card, push the card in again. You should hear another click when it unlocks and the card will pop out. The card should slide out easily; if you feel resistance pulling out the card, it is probably still locked in place. Do NOT try to pry or force the SD card out of the slot, this will damage the locking mechanism and render the gator:log useless.


Locking Mechanism

Calculating Data Usage

For most users, we recommend checking out our 1GB SD card. In most cases, this should hold enough data for a few sensors (depending on the amount of data you are storing and how quickly you are sampling that data).

Example Case:
  • Our 1GB SD card has about 970MB of storage capacity
  • Recording from 10 sensors
  • Each sensor sends 20 characters of data
  • Sampling rate of 1 ms

or

At 4850 seconds, that gives you about 1.3 hours of recording time. Now 1 ms is a pretty high data sampling rate, if you reduce that to 10 ms (or 100 times per second) and your recording time increases to about 13.5 hours.

If users need a longer recording time, they can change to an SD card with a higher storage capacity, change how often data is recorded, decrease the number of sensors used, or reduce the amount of characters stored per data set.

Status Indicator LEDs

There are two status LEDs on the gator:log to help with troubleshooting.

Status LEDs
Status LEDs: ST1 is blue and ST2 is green.

ST1 (Blue)

This blue indicator LED is attached to pad 5 of the ATmega328P. Mostly, users only need to be aware that this LED blinks when serial communication is functioning (i.e. data is being sent from the micro:bit to the gator:log).

ST2 (Green)

This green LED is connected to the SPI clock line on the ATmega328P. Mostly, users only need to be aware that this LED only blinks when the when the gator:log is recording data to the µSD card.

Note: If you are only sending short bursts of data, the green ST2 LED will be a lot more dim compared to the blue ST1 LED. You may need to cover it with your hands to see the LED blink clearly.


LED Brightness

Serial Connection

Serial is an asynchronous communication protocol used to transfer data between devices. It is a 2-wire connection consisting of RX (receiving data in) and TX (transmitting data out). It's important to know that the RX and TX labels are with respect to the device itself. So the RX from one device should go to the TX of the other, and vice-versa.

Serial Connection
Serial connection pads.

Hardware Assembly

Note: The gator:log will NOT function properly when used with the gator:bit. Users should use the gator:bit (v2) with the gator:log for it to operate properly.

Connecting your gator:log to the to the gator:bit (v2) is simple. The board can also be daisy-chained with other I2C boards. This can easily be done with alligator cables or these special banana cables.

Hardware Assembly
Hardware assembly of connections used in example. Click to enlarge.
Multiple Boards
Example of connecting multiple gator accessory boards. Click to enlarge.
gator:log GND 3V3 RX TX RST
gator:bit (v2) GND 3.3V OUT P15 (MOSI) P14 (MISO) P13 (SCK)

Adding the MakeCode Extension

Note: This tutorial assumes you are familiar with MakeCode, the gato:bit (v2), and the micro:bit board.

The easiest way to get started using the gator:log is to use Microsoft MakeCode, a web-based block editor. This tutorial assumes you are familiar with the with MakeCode, the gator:bit (v2), and the micro:bit development board. If this is your first time check out this guides linked in the suggested reading section (above).

Installing Extensions

To get started with using MakeCode with the micro:bit, head over to the MakeCode for micro:bit website by Microsoft. Then, click the New Project button to start a new project and open the Editor. (*Yes, all you need to get start coding is a computer with internet access, an up-to-date web browser, and an available USB port!)

MakeCode Website
Click the New Project button to start a new project and open the Editor. Click on image to enlarge.

Once you have the editor up, click on the the Advanced block in the block library to reveal the drop down menu.

Editor
Click on the the Advanced block in the block library to reveal the drop down menu. Click on image to enlarge.

Finally, click on the Extensions block. This should bring up the extensions page. (*Alternatively, you could also click on the extensions link from the settings menu.)

Advanced Block
Click on the the Extensions block to open the extensions page. Click on image to enlarge.

There are two methods for finding the gator:log extension:

  • Search for the name used on the extension1.
  • Use the link to the GitHub repository for the pxt-package as the search term.

Extensions Page
Use the search bar to find the extension you want to install. Click on image to enlarge.

Note: Unfortunately, it does take time to get an extension approved by the micro:bit Educational Foundation before it can be searchable by name. Part of the requirements for the approval process involves a live product page. Therefore, at the time of the launch of this product, the extension has not been approved yet and the only method of adding the extension is to use the link to the GitHub repository of the pxt-package. We will update this tutorial as soon as the extension has been approved.

Search for the PXT-Package

Search for the gator:log extension using the GitHub repository link to the pxt-package:

https://github.com/sparkfun/pxt-gator-log

Search for Extension
Search for Extension. Then, click on the box to add it to the block library. Click on image to enlarge.

Then, click on the box for the extension to add it to the block library. The gator:log extension should now appear in the block library.

Extension in Block Library
Extension in the block library; click on the block to open menu options. Click on image to enlarge.

To verify that you have added the extension, click on the gator:log block to make sure that your drop down menu options match the image below.

Menu Options
Available blocks for the gator:log extension. Click on image to enlarge.

MakeCode Examples

Now that you have added the gator:particle extension to the Editor, lets start with some example code. Plug the micro:bit into your computer using an USB micro-B cable after you have assembled your hardware with the instructions from the previous section. The micro:bit should appear on your computer as a removable storage device.

USB Drive
The micro:bit showing up as a USB drive on a Windows computer. Click to enlarge.

To upload new code, this is where you will be copying the downloaded .hex file to later.

Block Functions

Initialize gator:log
This block should be pretty self explanatory, it sets the gator:log and SD card to they are ready to log data. You should use this within the on start block.

open file named "____"
This block should be pretty self explanatory, it opens a specific file. If the file can't be found in the current directory, a new file with the input name will be created. (*New files aren't actually created until there is data written into them.)

File Name- Input name of file to be opened. Standard 8.3 filenames are supported. For example:

  • 87654321.123 is acceptable.
  • 987654321.123 is not acceptable.

remove file "___"
This block should be pretty self explanatory, it deletes a file from the current directory

File Name- Input name of file to be to be deleted. Standard 8.3 filenames are used and wildcards (e.g. *) are supported.

create folder with name "___"
This block should be pretty self explanatory, creates a folder within the current directory.

Folder Name- Input name of sub-directory to be created.

change to "___" folder
This block should be pretty self explanatory, changes the current directory to a specific folder. If the folder can't be found in the current directory, a new folder with the input name will be created.

Folder Name- Input name of sub-directory to move to.

remove folder "___" and it's contents
This block should be pretty self explanatory, it deletes a folder and any content inside it.

Folder Name- Input name of directory to be deleted along with any files contained within it.

write line "___" to current file
This block writes data to the currently accessed file. If no specific file is accessed after initialization, by default this data is written to LOG00000.txt (created on initialization).

Data- Input data to be entered into current file. (Entry contains carriage return and next entry will begin on a new line.)

write "___" to current file
This block writes data to the currently accessed file. If no specific file is accessed after initialization, by default this data is written to LOG00000.txt (created on initialization).

Data- Input data to be entered into current file. (Entry does not contain a carriage return and next entry will begin on the same line after the previous entry.)

write line "___" at position ___
This block writes data to the currently accessed file at a specific character number. If no specific file is accessed after initialization, by default this data is written to LOG00000.txt (created on initialization).

  1. Data- Input data to be entered into current file. (Entry contains carriage return and next entry will begin on a new line.)
  2. Position- An integer for where in the current data the entry should begin.

Basic Test

Below, is a simple example of how to test the data logger. To use this example, there are multiple options for accessing the .hex file:

  • Replicate the block functions from the display below to copy the example project. Then download the .hex file.
  • Expand the display widow to pull up the example project. Then download the .hex file.
  • Use this link to pull up the example project. Then download the .hex file.
  • Download the .hex file from the button below or the link on the bottom of the display.

This code is relatively simple, in that it is used to test the buffer on the gator:log. The code expands the span of the dataset stored on each subsequent line; except when the length of digits increase, then is expands by 3. This was to limit the cycle time spent to map that out neatly. (With this code, I was able to max out the gator:log in several minutes; whereas, when mapped out neatly the gator:log had only reached the 200th line after 30 minutes.)

Logged Data
Example of logged test data set.

The µSD card was removed from the gator:log and opened on a computer. You will notice the config.txt and LOG00000.txt files, which are created on initialization. The sample data set for this example is stored in sample.txt.

Based on the recorded data set, the last full row was line 1737, which had 1743 characters stored before the gator:log reset itself. Now, we do not expect many users to reach data sets that long on a single line, but users should be aware of certain limitations.

It is always a best practice to test/verify that the gator:log will work properly for your application. It would be a disappointing to lose a bunch of data or miss out on something important.

Multiple Files

Below, is a simple example of how to write data to multiple files. Again, there are multiple options for accessing the .hex file:

This code is relatively simple, in that odd numbers are saved to the odd.txt file and even numbers are saved to the even.txt file. After loading this example and waiting a bit, you can remove the µSD card and open the odd.txt and even.txt files. You should see the corresponding integers stored in each file.

Troubleshooting the Extension

To manually install this extension in makecode, go to the "Extensions" tab on the left side of the makecode site:

alt text

In the location you'd normally search for an extension, you'll notice an upload button on the right:

alt text

Click on this, and you'll get a window allowing you to upload your own built extension. Navigate to where you saved the above extension hex, and upload it to your project.

alt text

You should be able to see the extension and its functions now. In addition, you'll be able to build and download your project to your variant of micro:bit.

alt text

Other Troubleshooting Tips

Below are common issues to check, if you are having problems with your gator:log.

Check the Status LED Behavior

The behavior of the status LEDs may indicate different issues:

  • ST1 LED:
    • 3 Blinks: The microSD card failed to initialize. You may need to format the card with FAT16/FAT32 on a computer.
    • No Blinking: The gator:log probably isn't receiving data across the RX pad. Double check your connections.
  • ST2 LED:
    • No Blinking: The gator:log probably isn't writing data to the SD card. Double check your SD card formatted properly, that the config.txt file is created on initialization, or your SD card isn't full.

Original gator:bit board

Double check which gator:bit board you are using. As mentioned earlier, the gator:log will not operate with the original gator:bit. Users must use the updated gator:bit (v2) board.

Add Delays Between Character Writes

By adding a small delay between data logging operations, you can give gator:log a chance to record its current buffer.

The gator:log may not save all the data properly, if there are a lot of characters being sent right next to each other. Inserting a small delay of 15ms between large character writes will help open:log record data without dropping characters.

Config File

The config.txt file is used to store the configuration settings for the ATmega328P to operate as a data logger. This file should not be modified. Changing the stored setting may potentially configure the gator:log in a way that locks users out. In which case, the gator:log may become unrecoverable without a special programmer. Users who have accidentally modified the file, can restore it with the following settings:

9600,26,3,0,1,1,0
baud,escape,esc#,mode,verb,echo,ignoreRX

Likewise, users who have bricked the gator:log may be able to insert a freshly formatted µSD card with a config.txt file containing the two lines as shown above.

Empty Files

The gator:log will not create a blank file without data. The file isn't actually created until data is put in it.

Double Check File Names

All file names should be alpha-numeric, according to the 8.3 filename guidelines. MyLOG1.txt is ok, but Hi !e _.txt will not work.

Format your µSD Card

Make sure that you format your card using a FAT16 or FAT32 format. (If you did not format your µSD card on a Windows OS, reformat the µSD card and create a DOS filesystem on the SD card.)

If you are running into issues writing to the SD card at high speeds, try to use a card with few or no files on it. (i.e. An 8GB µSD card with 3.1GB worth of ZIP files or MP3s has a slower response time than an empty card.)

Swap µSD Cards

There are many different types of card manufacturers, relabeled cards, card sizes, and card classes, and they may not all work properly. We have tested the following cards to work with the gator:log. If you run into an issue using one of these SD cards that you purchased from us (after formatting it properly), please create a post on our forum.

microSD Card with Adapter - 32GB (Class 10)

microSD Card with Adapter - 32GB (Class 10)

COM-14832
$26.95
1
microSD Card - 1GB (Class 4)

microSD Card - 1GB (Class 4)

COM-15107
$5.50

microSD Card with Adapter - 16GB (Class 10)

COM-13833
6 Retired

Old or Frequently Used Cards

All SD cards have a finite lifespan. A typical flash memory card unit has approximately 10,000 write/erase operations. The continued use of an old or frequently used SD card; may result in corrupted files or data.

Fakes and Counterfeits

Be wary of purchasing fake or counterfeit SD cards from overseas suppliers. The cost benefits may be tempting, but it can be a gamble.

Other Considerations

Below are a few other considerations for SD cards:

  • SD cards are somewhat fragile and will usually cease to function once damaged, structurally.
  • SD cards a usually waterproof to a certain degree, but should be clean and dry before use (including the hardware).
  • SD cards have a wide operating temperature, but may fail in extreme temperatures (though you may run into other hardware issues first).

Verify the Number of Files in the Root Directory

The gator:log will only support up to 65,534 log files in the root directory. We recommend reformatting your µSD card to clear space and improve logging speed.

If you still have questions or issues with this product, please create a post on our forum under the Gator Products topic.

Additionally, if you are an educator and you have class or application based questions, please create a post on our forum under the Educational Products topic.

Resources and Going Further

For more product information, check out the resources below:

Interested in the micro:bit? Check out some of these other micro:bit products:

micro:bit v2 Club Kit - Go Bundle 10-Pack

micro:bit v2 Club Kit - Go Bundle 10-Pack

KIT-17290
$175.00
4
SparkFun Inventor's Kit for micro:bit v2

SparkFun Inventor's Kit for micro:bit v2

KIT-17362
$53.50
SparkFun Inventor's Kit for micro:bit v2 Lab Pack

SparkFun Inventor's Kit for micro:bit v2 Lab Pack

LAB-17363
$460.00
SparkFun Educator Lab Pack for micro:bit v2

SparkFun Educator Lab Pack for micro:bit v2

LAB-17361
$320.95

Need some inspiration for your next project? Check out some of these other micro:bit product tutorials:

SparkFun Inventor's Kit for micro:bit Experiment Guide

This guide contains all the information you will need to explore the twelve circuits of the SparkFun Inventors Kit for micro:bit.

SparkFun gator:bit v2 Hookup Guide

The gator:bit v2 is a breakout board for the BBC micro:bit. The gator:bit exposes almost every pin on the micro:bit to clippable pad with circuit protection. It also has as built-in addressable LEDs and a built-in buzzer.

SparkFun gator:RTC Hookup Guide

The gator:RTC is an I2C based, real-time clock (RTC) for keeping time while your micro:bit isn't powered. This tutorial will get you started using the gator:RTC with the micro:bit platform.

SparkFun gator:log Hookup Guide

The gator:log is a serial communication based data logger. This tutorial will get you started using the gator:log with the micro:bit platform.