javascript-2020/sdcard

readme

### esp-idf component sdcard

full documentation in html format available at

[https://github.com/javascript-2020/javascript-2020.github.io/blob/main/micro-controllers/esp-idf/components/sdcard/sdcard.html](https://github.com/javascript-2020/javascript-2020.github.io/blob/main/micro-controllers/esp-idf/components/sdcard/sdcard.html)




## Using the component

Run the following command in your ESP-IDF project to install this component:

```

        idf.py add-dependency "javascript-2020/sdcard"
        
```


the library self initialises, so simply including

```

        #include "sdcard.h"
        
```

in your file will give access to the variable providing the functionality

```

        sdcard
        
```

---

>
> the spi example gives an example of mounting a sdcard on an spi bus
>
> the sdmmc example gives an example of mounting a sdcard on an sdmmc bus
>
> the test example gives examples of all functionality
>

---

## quick useage

```

        #include "sdcard.h"
        
        void app_main(){
        
              sdcard.spi.mount("/sdcard",40,39,42,41);
              
              sdcard.print_info("/sdcard");
              
        }//app_main
        
```

---

## api

---

### debug

debugging can be enabled by setting the property

```

        sdcard.debug    = true;
        
        // ...
        
        sdcard.debug    = false;
        
```

---


### sdcard.spi.mount

#### esp_err_t sdcard.spi.mount (const char* root,int cs,int clk,int mosi,int miso)

mount the card on spi bus

__return__

ESP_OK

some other error code

```

        char* root      = "/sdcard";
        int cs          = 40;
        int clk         = 39;
        int mosi        = 42;
        int miso        = 41;
        
        esp_err_t err   = sdcard.spi.mount(root,cs,clk,mosi,miso);
        
        if(err){
              printf("sdcard.spi.mount error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.spi.mount ok : %s",root);
        
```

---


### sdcard.spi.unmount

#### esp_err_t sdcard.spi.unmount (const char* root)

unmount card on spi bus

__return__

ESP_OK

some other error code

```

        char *root      = "/sdcard";
        
        esp_err_t err   = sdcard.spi.unmount(root);
        
        if(err){
              printf("sdcard.spi.unmount error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.spi.unmount ok : %s",root);
        
```

---


### sdcard.sdmmc.mount_data1

#### esp_err_t sdcard.sdmmc.mount_data1 (const char *root,int clk,int cmd,int d0)

mount sdcard on sdmmc bus with 1 bit data bus

__return__

ESP_OK

some other error code

```

        char *root      = "/sdcard";
        int clk         = 14;
        int cmd         = 15;
        int d0          = 2;
        
        esp_err_t err   = sdcard.sdmmc.mount_data1(root,clk,cmd,d0);
        
        if(err){
              printf("sdcard.sdmmc.mount_data1 error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.sdmmc.mount_data1 ok : %s",root);
        
```

---


### sdcard.sdmmc.mount_data4

#### esp_err_t sdcard.sdmmc.mount_data4 (const char *root,int clk,int cmd,int d0,int d1,int d2,int d3)

mount sdcard on sdmmc bus with 4 bit data bus

__return__

ESP_OK

some other error code

```

        char *root      = "/sdcard";
        int clk         = 14;
        int cmd         = 15;
        int d0          = 2;
        int d1          = 4;
        int d2          = 12;
        int d3          = 13;
        
        esp_err_t err   = sdcard.sdmmc.mount_data4(root,clk,cmd,d0,d1,d2,d3);
        
        if(err){
              printf("sdcard.sdmmc.mount_data4 error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.sdmmc.mount_data4 ok : %s",root);
        
```

---


#### esp_err_t sdcard.sdmmc.unmount (const char* root)

unmount sdcard from sdmmc bus

__return__

ESP_OK

some other error code

```

        esp_err_t err   = sdcard.sdmmc.unmount("/sdcard");
        
        if(err){
              printf("sdcard.sdmmc.unmount error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.sdmmc.unmount ok : %s",root);
        
```

---


### sdcard.format

#### esp_err_t sdcard.format (const char* root)

format sdcard

__return__

ESP_OK

some other error code

```

        esp_err_t err   = sdcard.format("/sdcard");
        
        if(err){
              printf("sdcard.format error (%d) %s\n",err,esp_err_to_name(err));
              return;
        }
        printf("sdcard.format ok : %s",root);
        
```

---


### sdcard.info

#### esp_err_t sdcard.info (const char* root,sdcard_info_t* info)

return print card info

__return__

ESP_OK

some other error code

```

        sdcard_info_t info;
        
        esp_err_t err   = sdcard.info("/sdcard",&info);
        
```

---

#### esp_err_t sdcard.info_print (const char* root)

utility function to quickly print card info to stdout

__return__

ESP_OK

some other error code

```

        sdcard.info_print("/sdcard");
        
```

---


### sdcard.file.read

#### esp_err_t sdcard.file.read (const char *path,void *buf,size_t *size)

read data from card, provide a buffer and the size of the buffer
the function will return how much data was actually read in size

__return__

ESP_OK

some other error code

`errno` will be set in case of io error

```

        size_t size     = 10;
        char *buf       = malloc(size);
        
        esp_err_t err   = sdcard.file.read("/sdcard/test.txt",buf,&size);
        
        if(err){
              printf("sdcard.file.read error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.read_offset

#### esp_err_t sdcard.file.read_offset (const char *path,size_t offset,void *buf,size_t *size)

read a file on the sdcard from offset into a buffer of given size
the actual size read will be placed in size after

__return__

ESP_OK

some other error code

`errno` will be set in case of io error

```

        char *file      = "/sdcard/test.txt";
        size_t offset   = 5;
        size_t size     = 10;
        char *buf       = malloc(size);
        
        esp_err_t err   = sdcard.file.read_offset(file,offset,buf,&size);
        
        if(err){
              printf("sdcard.file.read_offset error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.read_until

#### esp_err_t sdcard.file.read_until (const char *path,unsigned char search,size_t offset,size_t *num)

will read a file from offset and return the number of bytes ( inclusive ) until the search byte is found
utility function for reading csv files, lines of text terminated by \n

__return__

ESP_OK

some other error code

`errno` will be set for file io error

```

        char *file      = "/sdcard/test.txt";
        size_t offset   = 5;
        size_t num;
        char *buf       = malloc(10);
        
        esp_err_t err   = sdcard.file.read_until(file,'\n',offset,&num);
        
        if(err){
              printf("sdcard.file.read_until error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
        printf("%d from offset %d",num,offfset);
        
```

---


### sdcard.file.write

#### esp_err_t sdcard.file.write (const char* path,void* buf,size_t *size)

write a file, will truncate file on opening and create if does not exist

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file      = "/sdcard/test.txt";
        char txt[]      = "helloworld";
        size_t size     = strlen(txt);
        
        esp_err_t err   = sdcard.file.write(file,txt,size);
        
        if(err){
              printf("sdcard.file.write error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.write_offset

#### esp_err_t sdcard.file.write_offset (const char* path,size_t offset,void* buf,size_t *size)

write to a file at given offset, the buffer of size

file is created if doesnt exist

if offset is past eof, the file is padded with null bytes

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file      = "/sdcard/test.txt";
        size_t offset   = 10;
        size_t size     = 5;
        char *buf       = malloc(size);
        memset(buf,size,'x');
        
        esp_err_t err   = sdcard.file.write_offset(file,offset,buf,&size);
        
        if(err){
              printf("sdcard.file.write_offset error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.append

#### esp_err_t sdcard.file.append (const char *path,void *buf,size_t *size)

append data to file, the file is created if it doesnt exist

__return__

ESP_OK

some other error code

`errno` will be set in case of file io

```

        char *file    = "/sdcard/test.txt";
        char buf[]    = "helloworld";
        size_t size   = strlen(buf);
        
        esp_err_t err   = sdcard.file.append(file,buf,size);
        
        if(err){
              printf("sdcard.file.append error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.appendln

#### esp_err_t sdcard.file.appendln (const char *path,char *format,...)

append string data with automatic newline to file

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        char fmt[]    = "hello %s";
        
        esp_err_t err   = sdcard.file.appendln(file,fmt,"world");
        
        if(err){
              printf("sdcard.file.appendln error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.size

#### esp_err_t sdcard.file.size (const char* path,size_t* size)

return the size of a file

__return__

ESP_OK

some other error code

`errno` will be set in case of file io

```

        char *file    = "/sdcard/test.txt";
        size_t size;
        
        esp_err_t     = sdcard.file.size(file,&size);
        
        if(err){
              printf("sdcard.file.size error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---

### sdcard.file.exists

#### esp_err_t sdcard.file.exists (const char* path,bool *exists)

test whether a file exists

__return__

ESP_OK


some other error code

`errno` will be set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        bool exists;
        
        esp_err_t     = sdcard.file.exists(file,&exists);
        
        if(err){
              printf("sdcard.file.exists error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
        printf("%s exists ? %s",file,exists?"true":"false");
        
```

---


### sdcard.file.delete

#### esp_err_t sdcard.file.delete (const char* path)

delete a file

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        
        esp_err_t err   = sdcard.file.delete(file);
        
        if(err){
              printf("sdcard.file.delete error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.copy

#### esp_err_t sdcard.file.copy (const char* src,const char* dest)

copy a file

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *src       = "/sdcard/test.txt";
        char *dest      = "/sdcard/test-copy.txt";
        
        esp_err_t err   = sdcard.file.copy(src,dest);
        
        if(err){
              printf("sdcard.file.copy error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---

### sdcard.file.rename

#### esp_err_t sdcard.file.rename (const char *src,const char *dest)

rename file

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *src   = "/sdcard/test.txt";
        char *dest    = "/sdcard/test-rename.txt";
        
        esp_err_t err   = sdcard.file.rename(src,dest);
        
        if(err){
              printf("sdcard.file.rename error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.stat

#### esp_err_t sdcard.file.stat (const char *path,struct stat *buf)

get file stat structure

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        struct stat st;
        char *file    = "/sdcard/test.txt";
        
        esp_err_t err   = sdcard.file.stat(file,&st);
        
        if(err){
              printf("sdcard.file.stat error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.stat_print

#### esp_err_t sdcard.file.stat_print (const char *path)

utility function to print the stat structure to stdout

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        
        esp_err_t err   = sdcard.file.stat_print(file);
        
        if(err){
              printf("sdcard.file.stat_print error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.truncate

#### esp_err_t sdcard.file.truncate (const char *path)

truncate a file to zero length

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        
        esp_err_t err   = sdcard.file.truncate(file);
        
        if(err){
              printf("sdcard.file.truncate error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.file.print

#### esp_err_t sdcard.file.print (const char *path)

utility function to print the contents of a file to stdout

__return__

ESP_OK

some other error code

`errno` is set in case of file io error

```

        char *file    = "/sdcard/test.txt";
        
        esp_err_t err   = sdcard.file.print(file);
        
        if(err){
              printf("sdcard.file.print error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.num

#### esp_err_t sdcard.dir.num (const char* path,int* ct)

returns the number of files and directories in a directory

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir   = "/sdcard/tmp/";
        int num;
        
        esp_err_t err   = sdcard.dir.num(dir);
        
        if(err){
              printf("sdcard.dir.num error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.list_free

#### esp_err_t sdcard.dir.list_free (char*** ptr,int num)

utility function to free the memory assigned by a call to sdcard.dir.list

__return__

ESP_OK

```

        char *dir   = "/sdcard/tmp/";
        void **list;
        int num;
        
        esp_err_t err   = sdcard.dir.list(dir,&list,&num);
        
        if(err){
              printf("sdcard.dir.list error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
        err   = sdcard.dir.list_free(list,num);
        
        if(err){
              printf("sdcard.dir.list_free error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.list

#### esp_err_t sdcard.dir.list (const char* path,char*** ptr,int* num)

retrieve a directory listing, ptr is a an array of strings

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir   = "/sdcard/tmp/";
        void **list;
        int num;
        
        esp_err_t err   = sdcard.dir.list(dir,&list,&num);
        
        if(err){
              printf("sdcard.dir.list error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
        err   = sdcard.dir.list_free(list,num);
        
        if(err){
              printf("sdcard.dir.list_free error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.list_print

#### esp_err_t sdcard.dir.list_print (const char* path)

utility function to print the contents of a directory to stdout

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir       = "/sdcard/tmp/";
        
        esp_err_t err   = sdcard.dir.list_print(dir);
        
        if(err){
              printf("sdcard.dir.list_print error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.mkdir

#### esp_err_t sdcard.dir.mkdir (const char* path)

create a directory

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir   = "/sdcard/tmp/";
        
        esp_err_t err   = sdcard.dir.mkdir(dir);
        
        if(err){
              printf("sdcard.dir.mkdir error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.clear

#### esp_err_t sdcard.dir.clear (const char *path)

empty a directory of all files and sub directories

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir       = "/sdcard/tmp/";
        
        esp_err_t err   = sdcard.dir.clear(dir);
        
        if(err){
              printf("sdcard.dir.clear error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.delete

#### esp_err_t sdcard.dir.delete (const char *path)

delete a directory and all cointained files and directories

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

        char *dir   = "/sdcard/tmp/";
        
        esp_err_t err   = sdcard.dir.delete(dir);
        
        if(err){
              printf("sdcard.dir.delete error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.dir.exists

#### esp_err_t sdcard.dir.exists (const char* path,bool *exists)

test whether a directory exists

__return__

ESP_OK

some other error code

`errno` will be set in case of file io error

```

      char *dir   = "/sdcard/tmp/";
      bool exists;
      
      esp_err_t err   = sdcard.dir.exists(dir,&exists);
      
        if(err){
              printf("sdcard.dir.exists error : %s",root);
              printf("esp error (%d) %s",err,esp_err_to_name(err));
              if(errno){
                    printf("file io error (%d) %s",errno,strerror(errno));
              }
              return;
        }
        
```

---


### sdcard.fn.build_path

#### esp_err_t sdcard.fn.build_path (const char \*path,const char \*entry,char \*filepath,size_t size,char \*\*error)

utility function to build a path from an exists directory and filename

return

ESP_OK

some other error code

`errno` is set in case of file io error

```


```

---


### sdcard.fn.disp_buf

#### void sdcard.fn.disp_buf (const char *id,void *buf,size_t size)

utility function to display the contents of a buffer

return

void

```

        char buf[]    = "helloworld";
        size_t size   = strlen(buf);
        
        sdcard.fn.disp_bud("test",buf,size);
        
```

---


## Example

To run the provided example, create it as follows:

```
idf.py create-project-from-example "javascript-2020/sdcard:sdcard-test"
```

Then build as usual:

```
cd sdcard-test
idf.py build
```

And flash it to the board:

```
idf.py -p PORT flash monitor
```

## License

This component is provided under Apache 2.0 license, see [LICENSE](LICENSE.md) file for details.

## Contributing

Please check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.