« Close

Datasheets and User Guides

Software & Driver

 

21.0 SD Card (T7 Only) [T-Series Datasheet]

Overview - T7 Only

The T7-Pro ships with a 2GB (or larger) microSD card installed (SLC technology).  It might also be referred to as uSD, µSD, or just SD.

The T7 does not have the microSD card installed, but does have the card holder installed so a compatible microSD card can be installed in the field.

The retainer opens by sliding the metal piece forward, then lifting.

Currently microSDXC is not supported. Generally speaking, anything above 2GB is 'HC' meaning high capacity, and HC cards might need to be reformatted before they work.

The T7 supports FAT and FAT32 file systems, but some makes and sizes behave differently.  We recommend the following SD card format:

File System: FAT
Allocation unit size: 64 kilobytes

FAT32 with an allocation unit size of 16 kB or 32 kB sometimes works, but smaller allocation sizes generally do not.  On 2 GB cards it's possible to select FAT format with a 32 kB allocation size, and that sometimes works.

Care must be taken to ensure that power is not lost during file writing or disk corruption could occur.  The rated operating temperature of the SD card is -25°C to 85°C.  For extremely low temperatures, customers can buy industrial grade SD cards, such as the AF1GUDI-OEM, from ATP Electronics, Inc.

File and directory names are limited to ASCII characters only.

The maximum number of file handles that can be open at once on a T7 is 4.  One file handle is reserved for Modbus communication to allow programs to read files off of the SD card and the remaining 3 are available for Lua Scripts.

Standalone Data Logging

The microSD card is generally only useful for people doing standalone data logging through Lua scripting, since normal T7 operation is with a host connected (so the host can store data).  Standalone logging is an advanced topic.  We provide Lua examples for logging data to the microSD, but options for retrieving the data are somewhat limited (see next section).  Standalone logging is generally limited to command-response data rates.

For information about powering the T7-Pro see the VS, Power Supply Section of this datasheet.

As an alternative to true standalone logging with the T7-Pro, consider that any LabJack combined with a Raspberry Pi makes an incredibly powerful and flexible data logger.

Retrieving Data from the microSD Card

It is pretty easy to write data to the microSD card in a Lua script.  At this time there are a few options for retrieving the data from the microSD:

1.  Remove (or swap) the microSD from the T7 and put it in a card reader on a computer.  On non-OEM versions of the T7/T7-Pro, the enclosure must be opened to access the microSD holder.

2.  Use the beta SD utility for downloading files from the SD card via USB/Ethernet/WiFi on Windows, only.  Note that the microSD and WiFi share a serial bus inside the T7, so sometimes extra thought is required if using both at the same time.

3.  Use the registers described below to read data off the microSD.

Testing the microSD Card

Not all SD cards are compatible.  If you install a new or different SD card, we recommend the following tests to make sure it works.  If you have access to a Windows computer, we recommend downloading and running the T7uSD testing application published on the T-Series Additional Utility Applications page.

    A.  Check Kipling to make sure that the SD card is properly recognized and that the calibration status of the device is still good.

    1. Connect to the device with Kipling
    2. On the Device Info tab and make sure there is a green checkmark next to the SD Card Installed hardware option.
    3. Check to make sure the device's calibration status is still "Good".

    B. Check to make sure the SD card can be read and written.

    1. Connect to the device with Kipling.
    2. Download and run the Lua example script titled "Log voltage to file".
    3. Exit Kipling and open the SD Utility to verify that the file was written properly.

    C.  Check to make sure the T7's calibration constants can be read from the internal flash chip.

    1. If you are on a Windows computer, use LJStreamM to try streaming an analog input register from a T7.  If you get stream errors LJME_USING_DEFAULT_CALIBRATION (203) or LJME_INVALID_VALUE (1305), the microSD card being used is likely not compatible with the T7.

Errors Caused by Unsupported microSD Cards

  1. A device may get stuck in its recovery firmware version and report upgrade issues because the flash chip is not responding properly.
  2. A device may report that it is using default calibration values and it is unable to be used in stream mode. The device's calibration constants are read before streaming is started.
  3. A device may have issues when running Lua scripts that try to save data to the microSD card or errors may be reported by the SD Card utility indicating that a file can't be opened.

Accessing the microSD Card While Using WiFi

WiFi shares an internal serial bus with the SD card and Internal Flash, and at the start of joining WiFi needs about 3 seconds of uninterrupted access on this serial bus.  If a Lua script does file I/O operations during this time, then WiFi initialization will fail and the WiFi module will immediately try again.  If Lua file I/O occurs every 3 seconds or less, it is likely that WiFi will never be able to join.  A simple way to make sure WiFi can join, perhaps with a retry or two needed, is to only write every 5 seconds (or longer).

Use the following Lua pseudocode to write to a file once every 5 seconds, and read an analog input once every 500ms. See the "Log voltage to file" Lua examples in Kipling for an actual script example.

LJ.IntervalConfig(0, 500)  --set the DAQ interval to 500ms, should divide evenly into file access interval
LJ.IntervalConfig(1, 5000)  --set the file access interval to 5 seconds

TableSize = 5000/500
data = {}
DAQcount = 0

for i=1, TableSize do
  data[i] = 0
end

while true do
  if LJ.CheckInterval(0) then --if a data point needs to be collected
    data[DAQcount] = MB.R(0, 3)--collect a new reading from AIN0
    DAQcount = DAQcount + 1
  end
  if LJ.CheckInterval(1) then --file access interval complete
    appendToFile(data)          --save the data  to a file
    DAQcount = 0
  end
end

File I/O General Info

The T7 uses Unix-style file paths where the separator character is a slash: /

The root directory doesn't require a "/". For example, reading a file named "test.txt" in the "tmp" folder could be done with either this following path:

tmp/test.txt

or, alternately:

/tmp/test.txt 

Common File I/O Operations

See the Register Listing section below for register information.

Get the name of the current working directory (CWD):

  1. Write a value of 1 to FILE_IO_DIR_CURRENT. The error returned indicates whether there is a directory loaded as current. No error (0) indicates a valid directory.
  2. Read  FILE_IO_PATH_READ_LEN_BYTES.
  3. Read an array of size FILE_IO_PATH_READ_LEN_BYTES from FILE_IO_PATH_READ.
  4. Resultant string will be something like "/" for the root directory, or "/DIR1/DIR2" for a directory.

Get list of items in the CWD:

  1. Write a value of 1 to FILE_IO_DIR_FIRST. The error returned indicates whether anything was found. No error (0) indicates that something was found. FILE_IO_NOT_FOUND (2960) indicates that nothing was found.
  2. Read FILE_IO_PATH_READ_LEN_BYTES, FILE_IO_ATTRIBUTES, and FILE_IO_SIZE_BYTES. Store the attributes and size associated with each file.
  3. Read an array of size FILE_IO_PATH_READ_LEN_BYTES from FILE_IO_PATH_READ. This is the name of the file/folder.
  4. Write a value of 1 to FILE_IO_DIR_NEXT. The error returned indicates whether anything was found. No error (0) indicates that there are more items->go back to step 2. Each of the following errors indicate that there are no more items:
    • FILE_IO_END_OF_CWD (2966)
    • FILE_IO_INVALID_OBJECT (2809)
    • FILE_IO_NOT_FOUND (2960)

Change the CWD:

  1. Find from the list of items a directory to open, e.g. "/DIR1".  Directories can be parsed out of the list of items by analyzing their FILE_IO_ATTRIBUTES bitmask.  If bit 4 of the FILE_IO_ATTRIBUTES bitmask is set, then the item is a directory. 
  2. Write the directory name length in bytes to FILE_IO_PATH_WRITE_LEN_BYTES (ASCII, so each char is 1 byte, also don't forget to add 1 for the null terminator).
  3. Write the directory string (converted to an array of bytes, with null terminator) to FILE_IO_PATH_WRITE.  (array size = length from step 2)
  4. Write a value of 1 to FILE_IO_DIR_CHANGE.
  5. Done.  Optionally get a list of items in the new CWD.

Get disk size and free space:

  1. Read FILE_IO_DISK_SECTOR_SIZE_BYTES, FILE_IO_DISK_SECTORS_PER_CLUSTER, FILE_IO_DISK_TOTAL_CLUSTERS, FILE_IO_DISK_FREE_CLUSTERS. All disk parameters are captured when you read FILE_IO_DISK_SECTOR_SIZE_BYTES.
  2. Total size = SECTOR_SIZE * SECTORS_PER_CLUSTER * TOTAL_CLUSTERS. 
  3. Free size = SECTOR_SIZE * SECTORS_PER_CLUSTER * FREE_CLUSTERS.

Get disk format:

  1. Read FILE_IO_DISK_FORMAT_INDEX
  2. 2=FAT, 3=FAT32

Read a file:

  1. Write the length of the file name (including the null terminator) to FILE_IO_PATH_WRITE_LEN_BYTES
  2. Write the name to FILE_IO_PATH_WRITE (with null terminator)
  3. Write any value to FILE_IO_OPEN
  4. Read file data from FILE_IO_READ using the size from FILE_IO_SIZE_BYTES (FILE_IO_SIZE_BYTES can be read while getting a list of items in the CWD)
  5. Write a value of 1 to FILE_IO_CLOSE

Write a file:

  1. Modbus interface unimplemented. Users are typically expected to create files from onboard Lua scripts. Contact [email protected] if you are interested in creating files via Modbus.

Create a directory:

Unimplemented.  Since Lua scripts currently do not have the ability to write files anywhere except the root directory, this feature is not implemented.

Register Listing

 

 

File IO File Operations
Name Start Address Type Access

FILE_IO_OPEN             Write any value to this register to open a file. Must first designate which file to open by writing to FILE_IO_PATH_WRITE_LEN_BYTES then FILE_IO_PATH_WRITE.

60620 UINT16 W

FILE_IO_CLOSE             Write any value to this register to close the open file.

60621 UINT16 W

FILE_IO_WRITE             Unimplemented. This register is a buffer.

60654 BYTE W

FILE_IO_READ             Read the contents of a file. Must first write to FILE_IO_OPEN. Size of the file (in bytes) determined by FILE_IO_SIZE_BYTES. This register is a buffer. Underrun behavior - throws an error.

60656 BYTE R

FILE_IO_DELETE             Write any value to this register to delete the active file. Must first designate which file to delete by writing to FILE_IO_PATH_WRITE_LEN_BYTES then FILE_IO_PATH_WRITE.

60622 UINT16 W

FILE_IO_ATTRIBUTES             Bitmask: Bit0: Reserved, Bit1: Reserved, Bit2: Reserved, Bit3: Reserved, Bit4: 1=Directory, Bit5: 1=File. Used to differentiate files from directories/folders.

60623 UINT16 R

FILE_IO_SIZE_BYTES             The size of the file in bytes. Directories have 0 size.

60628 UINT32 R

Read from the disk information registers to get free space and other information.

 

File IO Disk Information
Name Start Address Type Access

FILE_IO_DISK_SECTOR_SIZE_BYTES             The size of each sector in the SD card in bytes. In Windows this is called the Allocation Size.

60630 UINT32 R

FILE_IO_DISK_SECTORS_PER_CLUSTER             The number of sectors in each cluster. Captured on read of FILE_IO_DISK_SECTOR_SIZE_BYTES.

60632 UINT32 R

FILE_IO_DISK_TOTAL_CLUSTERS             The total number of clusters in the SD card. Captured on read of FILE_IO_DISK_SECTOR_SIZE_BYTES.

60634 UINT32 R

FILE_IO_DISK_FREE_CLUSTERS             Free (available) clusters in the SD card. Used to determine free space. Captured on read of FILE_IO_DISK_SECTOR_SIZE_BYTES.

60636 UINT32 R

FILE_IO_DISK_FORMAT_INDEX             Used to determine the format of the SD card. 0=None or Unknown, 1=FAT12, 2=FAT16(Windows FAT), 3=FAT32

60638 UINT32 R

The registers that are type BYTE are AAI binary.

FILE IO and Lua
Name Start Address Type Access

FILE_IO_LUA_SWITCH_FILE             Write any value to this register to instruct Lua scripts to switch to a new file. Lua script should periodically check LJ.CheckFileFlag() to receive instruction, then call LJ.ClearFileFlag() after file switch is complete. Useful for applications that require continuous logging in a Lua script, and on-demand file access from a host.

60662 UINT32 R/W