¶ SD Card
¶ Overview
By default an SD card is not configured. If you want an SD card you need to set up sdcard and spi in your config.yaml . If you successfully setup both you will see messages like this:
[MSG:INFO: SPI SCK:gpio.18 MOSI:gpio.23 MISO:gpio.19]
[MSG:INFO: SD Card cs:gpio.5 dectect:I2SO.27]
¶ Supported SD Cards
MMC cards are not supported.
2 GB SD cards are not supported, because they use a different internal block size compared to all other sizes.
SD cards 64 GB and larger are supported only if they are reformatted into FAT-32 format. The factory format on large cards is ExFAT, which the libraries that we use do not handle. See the Card Formatting section below for more information.
We use an SPI interface. Not all SD cards support SPI.
In general, old, small cards work well, except as noted above.
¶ Config File
¶ spi Section
Here is the config file section for spi:
spi:
miso_pin: gpio.19
mosi_pin: gpio.23
sck_pin: gpio.18
- miso_pin must be a native pin to the microcontroller and have input capability
- mosi_pin must be a native pin to the microcontroller and have output capability
- sck_pin must be a native pin to the microcontroller and have output capability
It is recommended that you use the default pin numbers, because these have been thoroughly tested, but other pins should work.
¶ sdcard Section
You need an sdcard section with at least the cs_pin defined. The card_detect_pin is supported, but there are no features associated with it other than showing it in the startup messages.
Here is the config file section for sdcard:
sdcard:
cs_pin: gpio.5
card_detect_pin: NO_PIN
frequency_hz: 8000000
- cs_pin Chip select pin. Capabilities native, output
- card_detect_pin Capabilities input
- frequency_hz
- Type: Integer
- Range: 400000 to 20000000
- Default: 8000000
- Details: This sets the clock speed for the SPI bus used for this. If you have consistent problems with the SD card, try lower values for this.
¶ Fallback Configuration
For systems that use the default SPI pins, there is a way to access the SD Card without a config file. That can be useful for testing and other situations where your config file gets lost. See $SD/FallbackCS for more information.
¶ Control Commands
It is recommended you use the commands that start with $SD/. The numeric versions like [ESP210] are still supported and used by some senders, but they may be removed some day and the $SD/ type are easier to remember and support. Send $CMD to list all commands and also show the numeric versions of each command.
Note: If you have authentication enabled (which is not the default), you will need to supply a password for some of the commands. Send $SD/List pwd=admin (this assumes you are using the default password of "admin") to list files authenticated with the password "admin".
¶ $SD/Status - Get SD Card Status
Sending $SD/Status will return the current status of the SD card.
¶ $SD/List - Get SD Card Content
Sending $SD/List will list all the files. This is recursive and will search all subdirectories. Each file will print like this:
[FILE:/FOO.NC|SIZE:29547]
/FOO.NC is the filename including the directory (in this case the directory is the root). Files in the root directory are shown with a slash in front. Technically this is the proper name for the file, but you don't need to use it with the commands if the file is located in the root directory.
The number following SIZE: is the file size.
¶ $SD/Rename=oldname>newname
Renames existing files on the SD card
Example: $SD/Rename=foo.nc>bar.nc will rename existing file foo.nc to bar.nc.
¶ $SD/Run - Run File From SD Card
Sending $SD/Run=/Foo.nc will run file /Foo.nc
Notes:
- If in alarm mode, this command will fail with error 9
- To Pause/Restart Just use the normal grbl cycle start and feedhold commands
- To Stop/Quit a file Use Grbl Reset. The best way to do this is to do a feed hold then a Grbl Reset. The last line will be reported. Keep in mind that the feedhold will have stopped a move in progress and there will be more moves in the buffer. Restarting and resetting all the modal things is very tricky and left to the sender.
- Errors Any gcode errors in the SD card file will terminate the job. The offending line number of the file will be reported.
-
Status When an SD card job is running, the percent of bytes completed is appended to the status string, shown in the following example as SD:45.5:
<Idle|WPos:195.000,144.000,19.000|Bf:15,128|FS:0.000,0.000|Pn:P|WCO:-195.000,-144.000,-19.000|SD:45.5>
¶ $SD/Show=Foo.nc - View a File
Sending $SD/Show=Foo.nc will display the contents of file Foo.nc
¶ Adding or Uploading Files to SD Card
From a terminal program such as fluidterm prefix the local name with /sd and it will upload to the SD card. Sending /sd/Foo.nc will upload Foo.nc to the root directory.
Or you can add files by moving the SD card to a PC, or via the WebUI.
¶ $SD/Delete - Delete a File
Sending $SD/Delete=/Foo.nc will delete /Foo.nc.
¶ $SD/FallbackCS - Access SD without a config file
Sending $SD/FallbackCS=5 will setup GPIO 5 as the SD Card chip select pin to use in case the config file does not define cs_pin in the sdcard section (for example if the config file is missing). The default SPI pins will be used. After sending that command, you will need to reboot to apply it and thus enable the SD Card. Subsequently, any time that the system cannot configure the SD Card via the config file, it will setup the SD Card with the default SPI pins and that CS pin. GPIO 5 is the most commonly used GPIO for SD Card chip select, but of course you should use whatever is correct for your hardware.
If $SD/FallbackCS is set to its default value of -1, there will be no fallback behavior. In that case, missing information in the spibus: and sdcard: sections will result in no SD Card being configured, so the default pins for those functions will not be initialized.
¶ Card Formatting
FluidNC uses third party libraries to access SD cards. In general, the smallest, oldest and slowest cards tend to work best. As cards get larger, more and more RAM memory is needed to keep track of where files are located. That can be a problem on an ESP32, whose RAM is limited compared to, say, PCs.
Some people have trouble when SD cards have been formatted by Windows, but were able to solve the problem by formatting with SD Card Formater
The filesystem format must be FAT-32. ExFAT is not supported. Modern cards larger than 32GB usually come with ExFAT. To use such a card, you must use a partitioning tool to create a partition no larger than 32GB and format that as FAT32.
¶ File Names
The maximum length of a filename or subdirectory name is 30 characters. That limit applies to each component of the path. The overall path can be longer, but it is best to keep the overall length down to 100 characters or so, lest it exceed the length of a command line or some other internal buffer.
¶ File Sizes
FAT-32 has a limitation of a maximum individual file size of 4GB. That should not be a problem, as an individual GCode files rarely exceeds a few megabytes.
¶ Help & Troubleshooting
-
SD Card Size Make sure it is less than 64GB and not 2GB (due to a block size issue). Generally the smaller, low speed cards work best.
-
Card Format Format the card with FAT32.
-
Files Try testing with only a few files. Use filenames with 8 bit ASCII printable characters and less than 30 characters.
-
Getting responses with "No SD Card" Check your startup messages with
$SSto see if the card has any configuration errors or other information about the SD Card setup. Many controllers do not support a physical card detect pin of the socket, so card not found type message mean the card did not respond. -
Try using a simple terminal Try using a simple terminal like FluidTerm or the terminal with the Web Installer. This simplifies things and can help diagnose the problem. Send $SD/List to in the terminal to show the contents. The response should look something like this, with your files listed.
$sd/list
[DIR:System Volume Information]
[FILE: WPSettings.dat|SIZE:12]
[FILE: IndexerVolumeGuid|SIZE:76]
[FILE: myfile_1.nc|SIZE:38]
[FILE: myfile_2.nc|SIZE:13425]
[/sd/ Free:14.83 GB Used:128.00 KB Total:14.83 GB]
ok
- Try lowering the SPI frequency In the sdcard: section of your config file use a lower frequency than the default.
sdcard:
cs_pin: gpio.5
card_detect_pin: NO_PIN
frequency_hz: 400000
- It does not work with my DIY setup or adapter SD cards are very layout (connections) and timing sensitive. Many people have reported that their hand made circuits do not work. Some of these will work with example programs but not FluidNC. The examples use a different Espressif (ESP32 company) library than the Arduino style examples. The Arduino library uses a slower speed, so you can try to lower the frequency_hz: setting to 10000000 or 1000000. We are sorry, but we cannot help you if your hand made circuit does not work.