Änderungen
Aus Hackerspace Ffm
= About =
Play audio files with your Arduino in decent quality from SD card, only very few additional hardware required.
* Supports SD and SDHC cards formated with FAT16 or FAT32
=== Restrictions ===
* Audio file must be converted prior use
* Audio files must reside in root directory of card
* Minimum controller required: ATmega168. ATmega8 is too low on RAM.
= Usuage =
== Quickstart guide ==
* Install library: Unzip all to your /libraries/ folder.
Be careful that the audio output pins are digital ports that carry a positive voltage between 0V and 5V. It is not a good idea to have a DC voltage at line-inputs or smaller speakers as there will be a steady current flow. Therefore at least a resistor and/or a capacitor should be connected in series. For a start use at least 100 ohm or a capacitor between 100nF and 100uF. For line inputs use a voltage divider or poti to reduce the voltage.
= API reference =
== Constants ==
Here an overview of the constants used.
<pre>
#define SSDA_VERSIONSTRING "1.00"
// Sound Mode Flags
#define SSDA_MODE_FULLRATE 0x00 // 62.500 kHz @ 16 MHz, 31.250 kHz @ 8 MHz
#define SSDA_MODE_HALFRATE 0x10 // 31.250 kHz @ 16 MHz, 15.625 kHz @ 8 MHz
#define SSDA_MODE_MONO 0x00 // Use only 1st PWM pin
#define SSDA_MODE_STEREO 0x01 // Use both PWM pins for stereo output
#define SSDA_MODE_MONO_BRIDGE 0x02 // Use both PWM pins for more power
// Error codes from SimpleSDAudio, see other sd_l*.h for more error codes
#define SSDA_ERROR_NULL 0x80 // Null pointer
#define SSDA_ERROR_BUFTOSMALL 0x81 // Buffer to small
#define SSDA_ERROR_NOT_INIT 0x82 // System not initialized properly
</pre>
== Class name and default instance ==
<pre>class SdPlayClass { ... }</pre>
<pre>extern SdPlayClass SdPlay;</pre>
The name of the class is SdPlayClass. One instance is
already created for use and is named SdPlay.
== Public class functions ==
==== init() ====
<pre>boolean init(uint8_t soundMode);</pre>
Call this to initialze the library and set sound mode. This
function will also aquire the needed buffer (if not
already set manually using setWorkBuffer), initialize SD card
and sets up all used pins.
A combination of the following flags must be provided as
argument (combine via or-ing):
Sample rate setting flags
* SSDA_MODE_FULLRATE - 62.500 kHz @ 16 MHz, 31.250 kHz @ 8 MHz
* SSDA_MODE_HALFRATE - 31.250 kHz @ 16 MHz, 15.625 kHz @ 8 MHz
Output channel configuration flags
* SSDA_MODE_MONO - Use only 1st PWM pin
* SSDA_MODE_STEREO - Use both PWM pins for stereo output
* SSDA_MODE_MONO_BRIDGE - Use both PWM pins for more power
The function return true if successfull, false if an error
occured. You can use getLastError() to retrieve the error code.
Typical reasons for errors are wrong SD card connection or
too low RAM (1k heap required) for internal buffer available.
==== setFile() ====
<pre>boolean setFile(char *fileName);</pre>
After init was successfull, call this to select audio file by
providing the filename in 8.3 format.
The function return true if successfull, false if an error
occured. You can use getLastError() to retrieve the error code.
Typical reasons for errors are that the file was not found.
==== worker() ====
<pre>void worker(void); </pre>
Call this continually at least as long as the audio playback
is running. This function fills the internal playback buffer
by reading the next sectors from SD card.
You can´t call this function too often, but a buffer underrun
can occur when the time between two calls are too long.
==== play() ====
<pre>void play(void);</pre>
If audio is not playing, playing will be started.
If it is already playing, it will start playing from zero again.
==== stop() ====
<pre>void stop(void);</pre>
Stops playback if playing, sets playposition to zero.
==== pause() ====
<pre>void pause(void);</pre>
Pauses playing if not playing, resumes playing if was paused.
==== setSDCSPin() ====
<pre>void setSDCSPin(uint8_t csPin);</pre>
Call this before init to set SD-Cards CS-Pin to other than default.
==== setWorkBuffer() ====
<pre>void setWorkBuffer(uint8_t *pBuf, uint16_t bufSize);</pre>
Call this if you want to use your own buffer (at least 1024 bytes, must be multiple of 512).
Call this before init and then init will use this buffer instead
using malloc to create its own.
==== deInit() ====
<pre>void deInit(void);</pre>
Call this to free resources like buffer, release SD card pins,
audio interrupts and audio pins.
==== dir() ====
<pre>void dir(void (*callback)(char *));</pre>
Output the directory of the SD card. A pointer to a callback
function must be provided.
Usage example:
<pre>
...
// setup global callback function
void dir_callback(char *buf) {
Serial.println(buf);
}
...
// somewhere after initialization
SdPlay.dir(&dir_callback);
</pre>
==== isStopped(), isPlaying(), isPaused() ====
<pre>
boolean isStopped(void);
boolean isPlaying(void);
boolean isPaused(void);
</pre>
Returns the current state of the playback.
==== isUnderrunOccured() ====
<pre>boolean isUnderrunOccured(void);</pre>
Returns if the internal underrun-flag is set and clears it. If audio sounds strange or has dropouts, test if underruns are the cause.
==== getLastError() ====
<pre>uint8_t getLastError(void);</pre>
Retrieve the last error code and clears it. To analyse the error reason, take a look also at the files sd_l1.h and sd_l2.h of the library to find the meaning of the code.
