OpenLog Hookup Guide

Contributors: Nate, Toni_K

Command Set

You can interface with the OpenLog via a serial terminal. The following commands will help you read, write, and delete files, as well as change the settings of the OpenLog. You will need to be in Command Mode in order to use the following settings.

While the OpenLog is in Command Mode, STAT1 will toggle on/off for every character received. The LED will stay on until the next character is received.

File Manipulation

• new File- Creates a new file named File in the current directory. Standard 8.3 filenames are supported. For example, "87654321.123" is acceptable, while "987654321.123" is not.

  • Example: new file1.txt

• append File - Append text to the end of File. Serial data is then read from the UART in a stream and adds it to the file. It is not echoed over the serial terminal. If File does not exist when this function is called, the file will be created.

  • Example: append newfile.csv

• write File OFFSET - Write text to File from the location OFFSET within the file. The text is read from the UART, line by line and echoed back. To exit this state, send an empty line.

  • Example: write logs.txt 516

• rm File - Deletes File from the current directory. Wildcards are supported.

  • Example: rm README.txt

• size File - Output size of File in bytes.

  • Example: size Log112.csv
  • Output: 11

• read File + START+ LENGTH TYPE - Output the content of File starting from START and going for LENGTH. If START is omitted, the entire file is reported. If LENGTH is omitted, the entire contents from the starting point is reported. If TYPE is omitted, the OpenLog will default to reporting in ASCII. There are three output TYPEs:

  • ASCII = 1
  • HEX = 2
  • RAW = 3

  You may leave off some trailing arguments. Check the following examples.

  Basic read + omitted flags:

  • Example: read LOG00004.txt
  • Output: Accelerometer X=12 Y=215 Z=317

  Read from start 0 with length of 5:

  • Example: read LOG00004.txt 0 5
  • Output: Accel

  Read from position 1 with a length of 5 in HEX:

  • Example: read LOG00004.txt 1 5 2
  • Output: 63 63 65 6C

  Read from position 0 with a length of 50 in RAW:

  • Example: read LOG00137.txt 0 50 3
  • Output: André-- -þ Extended Character Test

• cat File - Write the content of a file in hex to the serial monitor for viewing. This is sometimes helpful to see that a file is recording correctly without having to pull the SD card and view the file on a computer.

  • Example: cat LOG00004.txt
  • Output: 00000000: 41 63 65 6c 3a 20 31

Directory Manipulation

• ls - Lists all contents of the current directory. Wildcards are supported.

  • Example: ls
  • Output: \src

• md Subdirectory - Create Subdirectory in the current directory.

  • Example: md Example_Sketches

• cd Subdirectory - Change to Subdirectory.

  • Example: cd Hello_World

• cd .. - Change to a lower directory in the tree. Note that there is a space between 'cd' and '..'. This allows the string parser to see the cd command.

  • Example: cd ..

• rm Subdirectory - Deletes Subdirectory. The directory must be empty for this command to work.

  • Example: rm temps

• rm -rf Directory - Deletes Directory and any files contained within it.

  • Example: rm -rf Libraries

Low Level Function Commands

• ? - This command will pull up a list of available commands on the OpenLog.

• disk - Show card manufacturer ID, serial number, manufacture date and card size. Example output is:

  Card type: SD2
  Manufacturer ID: 3
  OEM ID: SD
  Product: SU01G
  Version: 8.0
  Serial number: 39723042
  Manufacturing date: 1/2010
  Card Size: 965120 KB
  

• init - Reinitialize the system and reopen the SD card. This is helpful if the SD card stops responding.

• sync - Synchronizes the current contents of the buffer to the SD card. This command is useful if you have less than 512 characters in the buffer and want to record those on the SD card.

• reset - Jumps OpenLog to location zero, reruns bootloader and then init code. This command is helpful if you need to edit the config file, reset the OpenLog and start using the new configuration. Power cycling is still the preferred method for resetting the board, but this option is available.

System Settings

These settings can be manually updated, or edited in the config.txt file.

• echo STATE - Changes the state of the system echo, and is stored in system memory. STATE can either be on or off. While on, the OpenLog will echo received serial data on the command prompt. While off, the system does not read back received characters.

• verbose STATE - Changes the state of verbose error reporting. STATE can either be on or off. This command is stored in memory. By turning off verbose errors, OpenLog will respond with only a ! if there is an error rather than unknown command: COMMAND. The ! character is easier for embedded systems to parse than the full error. If you are using a terminal, leaving verbose on will allow you to see full error messages.

• baud - This command will open up a system menu allowing the user to enter a baud rate. Any baud rate between 300bps and 1Mbps is supported. The baud rate selection is immediate, and the OpenLog requires a power cycle for the settings to take effect. The baud rate is stored to EEPROM and is loaded every time OpenLog powers up. The default is 9600 8N1.

• set - This command opens a system menu to select the boot up mode. These settings will occur at the next power-on and are stored in non-volatile EEPROM.

  • New File Logging - This mode creates a new file each time OpenLog powers up. OpenLog will transmit 1 (UART is alive), 2 (SD card is initialized), then < (OpenLog is ready to receive data). All data will be recorded to a LOG#####.txt. The ##### number increases every time OpenLog powers up (the max is 65533 logs). The number is stored in EEPROM and can be reset from the set menu. All received characters are not echoed. You can exit this mode and enter command mode by sending CTRL+z (ASCII 26). All buffered data will be stored.
  Note: If too many logs have been created, OpenLog will output error **Too many logs**, exit this mode, and drop to Command Prompt. The serial output will look like `12!Too many logs!`.

  • Append File Logging - Also known as sequential mode, this mode creates a file called SEQLOG.txt if it is not already there, and appends any received data to the file. OpenLog will transmit 12< at which time OpenLog is ready to receive data. Characters are not echoed. You can exit this mode and enter command mode by sending CTRL+z (ASCII 26). All buffered data will be stored.

  • Command Prompt - OpenLog will transmit 12> at which time the system is ready to receive commands. Note that the > sign indicates OpenLog is ready to receive commands, not data. You can create files and append data to files, but this requires some serial parsing (for error checking), so we do not set this mode by default.

  • Reset New File Number - This mode will reset the log file number to LOG000.txt. This is helpful if you have recently cleared out a microSD card and want the log file numbers to start over again.

  • New Escape Character - This option allows the user to enter a character such as CTRL+z or $, and set this as the new escape character. This setting is reset to CTRL+z during an emergency reset.

  • Number of Escape Characters - This option allows the user to enter a character (such as 1, 3, or 17), updating the new number of escape characters needed to drop to command mode. For example, entering 8 will require the user to hit CTRL+z eight times to get to command mode. This setting is reset to 3 during an emergency reset.

  Escape Characters Explanation:The reason OpenLog requires `CTRL+z` hit 3 times to enter command mode is to prevent the board accidentally being reset during upload of new code from the Arduino IDE. There is the chance that the board would see the `CTRL+z` character coming through during bootloading (an issue we saw in the early versions of the OpenLog firmware), so this aims to prevent that. If you ever suspect your board has been bricked due to this, you can always do an emergency reset by holding the RX pin to ground during power up.