A Better SD Library with RT-Thread

Arduino Web Editor

RT-Thread IoT OS

Arduino MKR ZERO (I2S bus & SD for sound, music & digital audio data)

Arduino IDE

<h3 >Background</h3>The SD library shipped with Arduino IDE is handy, however lacks features like exFAT, LFN (long filename) and non-English characters support. This article is introducing an alternate SD card driver (based on RT-Thread) to address those issues.<h3 >RT-Thread</h3><a href="https://github.com/RT-Thread/rt-thread">RT-Thread </a>is a free and open source (Apache License 2.0) RTOS and available <a href="https://github.com/onelife/Arduino_RT-Thread">in the form of Arduino library</a>. There is another article (<a href="https://create.arduino.cc/projecthub/onelife/multitasking-on-arduino-b5f216">Multitasking on Arduino</a>) available to get the basic idea of RT-Thread.Let's start by installing the library through Arduino IDE's library manager. (This article is based on RT-Thread library version 0.4.4.)<h3 >SD Card Driver (TL;DR)</h3>(If you are not interested in the implementationand just want to know how to use it, please skip this section.)SD card support in RT-Thread library is in the form of DFS (device file system), which is part of RT-Thread architecture. FAT is one of the file system supported by RT-Thread. (In version 0.4.4 of RT-Thread library, FAT is the only supported file system.)The FAT DFS itself is based on the excellent work of <a href="http://elm-chan.org/fsw/ff/00index_e.html">ChaN's FatFs project</a>.A standard RT-Thread DFS provides the following file system and file interfaces:<pre ><code >/* File system operations */ struct dfs_filesystem_ops { const char *name; uint32_t flags; /* flags for file system operations */ /* operations for file */ const struct dfs_file_ops *fops; /* mount and unmount file system */ int (*mount) (struct dfs_filesystem *fs, unsigned long rwflag, const void *data); int (*unmount) (struct dfs_filesystem *fs); /* make a file system */ int (*mkfs) (rt_device_t devid); int (*statfs) (struct dfs_filesystem *fs, struct statfs *buf); int (*unlink) (struct dfs_filesystem *fs, const char *pathname); int (*stat) (struct dfs_filesystem *fs, const char *filename, struct stat *buf); int (*rename) (struct dfs_filesystem *fs, const char *oldpath, const char *newpath); }; /* File operations */ struct dfs_file_ops { int (*open) (struct dfs_fd *fd); int (*close) (struct dfs_fd *fd); int (*ioctl) (struct dfs_fd *fd, int cmd, void *args); int (*read) (struct dfs_fd *fd, void *buf, size_t count); int (*write) (struct dfs_fd *fd, const void *buf, size_t count); int (*flush) (struct dfs_fd *fd); int (*lseek) (struct dfs_fd *fd, off_t offset); int (*getdents) (struct dfs_fd *fd, struct dirent *dirp, uint32_t count); int (*poll) (struct dfs_fd *fd, struct rt_pollreq *req); } </code></pre>A specific DFS may implement all or some of them. When the time of mounting DFS, e.g. <code >dfs_mount(&#34;SD&#34;, &#34;/&#34;, &#34;elm&#34;, 0, 0)</code>, the specific DFS will be bound to a device. In this case the DFS &#34;elm&#34; (FatFs) bound to device &#34;SD&#34;.A standard RT-Thread device provides the following interface:<pre ><code >/* operations set for device object */ struct rt_device_ops { /* common device interface */ rt_err_t (*init) (rt_device_t dev); rt_err_t (*open) (rt_device_t dev, rt_uint16_t oflag); rt_err_t (*close) (rt_device_t dev); rt_size_t (*read) (rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size); rt_size_t (*write) (rt_device_t dev, rt_off_t pos, const void *buffer, rt_size_t size); rt_err_t (*control)(rt_device_t dev, int cmd, void *args); }; </code></pre>A specific device may implement all or none (set function pointer to NULL) of them.In the library, the device named &#34;SD&#34; implements SD card access related functions, which is involved a lower level device named &#34;SPI1&#34; in case of MKRZERO board. And the SPI device finally involved Arduino SPI library.<h3 >Data Logger Example</h3>The Arduino SD library provides an example named &#34;Datalogger&#34;. The same example is available also in RT-Thread library as listed in Code section below.The difference is that, in the example code below there is one second interval between sampling and only do it for 10 times.You may be already noticed the comment above <code >open()</code> function. To open an existing file and remove all its content can be done simply by replace <code >O_APPEND</code> with <code >O_TRUNC</code> flag.When running the example below with MKRZERO board, you may observe the following output from Serial Monitor: <pre ><code >\\ | / - RT - Thread Operating System / | \\ 4.0.1 build Apr 17 2019 2006 - 2019 Copyright by rt-thread team + Mount SD to &#34;/&#34; 416,347,312 finsh /&gt;436,369,335 442,375,340 449,376,338 449,375,346 429,374,341 447,369,342 449,363,338 426,363,334 419,353,327 </code></pre><h3 >Manipulation with Shell</h3>The real advantage of using RT-Thread library is that it enables you to manipulate files with (FinSH) shell commands.In Serial Monitororother serial terminal tools, enter <code >ls()</code> command will show the list of files in current directory (in this case &#34;/&#34;) as below.<pre ><code >ls() Directory /: DATALOG.TXT 240 HI_UTF8.TXT 35 A_REAL~1.TXT 22 0, 0x00000000 </code></pre>The number behind the file name is the file size in bytes. In the screenshot above, the size of &#34;datalog.txt&#34; is 240-byte because I run the example twice.Enter <code >cat(&#34;datalog.txt&#34;)</code> command will show the content of &#34;datalog.txt&#34; to confirm that there are 20 records.<pre ><code >finsh /&gt;cat(&#34;datalog.txt&#34;) 464,358,333 464,368,336 480,381,354 447,364,346 443,363,340 441,365,343 463,371,345 467,374,313 447,364,345 465,369,346 416,347,312 436,369,335 442,375,340 449,376,338 449,375,346 429,374,341 447,369,342 449,363,338 426,363,334 419,353,327 0, 0x00000000 </code></pre>There are also <code >copy()</code> and <code >rm()</code> commands.<pre ><code >finsh /&gt;copy(&#34;datalog.txt&#34;, &#34;copy.txt&#34;) 0, 0x00000000 finsh /&gt;ls() Directory /: COPY.TXT 240 DATALOG.TXT 240 HI_UTF8.TXT 35 A_REAL~1.TXT 22 0, 0x00000000 finsh /&gt;rm(&#34;copy.txt&#34;) 0, 0x00000000 finsh /&gt;ls() Directory /: DATALOG.TXT 240 HI_UTF8.TXT 35 A_REAL~1.TXT 22 0, 0x00000000 </code></pre>To list all the available commands, enter <code >list()</code>.<pre ><code >finsh /&gt;list() --Function List: hello -- say hello world version -- show RT-Thread version information list -- list available commands list_mem -- list memory usage information list_thread -- list thread list_sem -- list semaphore in system list_mutex -- list mutex in system list_event -- list event in system list_mb -- list mail box in system list_mq -- list message queue in system list_memp -- list memory pool in system list_timer -- list timer in system list_dev -- list device in system mkfs -- make a file system df -- get disk free mkdir -- create a directory cd -- change current working directory ls -- list directory contents rm -- remove files or directories cat -- print file content copy -- copy file or dir list_sd -- show SD information --Variable List: dummy -- dummy variable for finsh 0, 0x00000000 </code></pre><h3 >ExFAT, LFN and Non-English Characters Support</h3>ExFAT, LFN (long filename) and non-English characters support are not enabled by default (to make the example smaller). Turning on the following config in &#34;rtconfig.h&#34; (located in RT-Thread library directory) to enable those features.<pre ><code >#define RT_DFS_ELM_USE_EXFAT #define RT_DFS_ELM_USE_LFN (2) #define RT_DFS_ELM_MAX_LFN (255) #define RT_DFS_ELM_CODE_PAGE 936 </code></pre>RT_DFS_ELM_MAX_LFN represents the maximum length of file name and can be in range of 12 to 255.RT_DFS_ELM_CODE_PAGE is set to 437 for US by default, changed to 936 will enable simplified Chinese support as shown below.<pre ><code >finsh /&gt;ls() Directory /: DATALOG.TXT 240 hi_utf8.txt 35 a_really_long_file_name.txt22 0, 0x00000000 finsh /&gt;cat(&#34;hi_utf8.txt&#34;) Hello, world! 世界，你好！\t0, 0x00000000 </code></pre><h3 >Next Steps</h3><ul ><li ><a href="https://create.arduino.cc/projecthub/onelife/multitasking-on-arduino-b5f216">Multitasking on Arduino</a></li></ul><ul ><li >RT-Thread Primer (coming soon) </li></ul>

A Better SD Library with RT-Thread

Do you need to have exFAT support? Use long filename? Open multiple files? Or read files with non-English characters? Then check this out!