Skip to content

AudioMoth Library

OpenAcousticDevices edited this page Sep 25, 2018 · 20 revisions

The AudioMoth library is defined in audioMoth.h. The library defines a number of constants and enumerations, and a large number of function prototypes that allow complete control of the AudioMoth hardware.

Definitions

All applications should maintain a firmware version (e.g. 1.0.0) and a firmware description (e.g. AudioMoth-Firmware-Basic) which can be accessed through the desktop tools. The number of bytes used to store and transfer these are defined here.

#define AM_FIRMWARE_VERSION_LENGTH             3

#define AM_FIRMWARE_DESCRIPTION_LENGTH         32

AudioMoth incorporates a 256KB external SRAM chip, connected to the Wonder Gecko micro-controller through its External Bus Interface (EBI). This external memory is mapped to a specific location in the Wonder Gecko address space and can accessed directly from within the application C code.

#define AM_EXTERNAL_SRAM_START_ADDRESS         0x80000000

#define AM_EXTERNAL_SRAM_SIZE_IN_BYTES         (256 * 1024)

The back-up domain of the Wonder Gecko supports 512 bytes of SRAM which are persistent across power-down. The AudioMoth reserves 32 of these for internal use, and the rest are free for applications to use.

#define AM_BACKUP_DOMAIN_START_ADDRESS         0x40081120

#define AM_BACKUP_DOMAIN_SIZE_IN_BYTES         480

Each AudioMoth has a unique ID which is mapped to an 8-byte memory location and can be used by applications to uniquely identify devices.

#define AM_UNIQUE_ID_START_ADDRESS             0xFE081F0

#define AM_UNIQUE_ID_SIZE_IN_BYTES             8

Enumerations

The AudioMoth library defines a number of enumerations that are used by subsequent functions to query the state of the device and to set the clock source.

typedef enum {AM_SWITCH_CUSTOM, AM_SWITCH_DEFAULT, AM_SWITCH_USB, AM_SWITCH_NONE} AM_switchPosition_t;

typedef enum {AM_HFRCO_1MHZ, AM_HFRCO_7MHZ, AM_HFRCO_11MHZ, AM_HFRCO_14MHZ, AM_HFRCO_21MHZ, AM_HFRCO_28MHZ, AM_HFXO} AM_clockFrequency_t;

typedef enum {AM_BATTERY_LOW, AM_BATTERY_3V6, AM_BATTERY_3V7, AM_BATTERY_3V8, AM_BATTERY_3V9, AM_BATTERY_4V0, AM_BATTERY_4V1, AM_BATTERY_4V2, AM_BATTERY_4V3, AM_BATTERY_4V4, AM_BATTERY_4V5, AM_BATTERY_4V6, AM_BATTERY_4V7, AM_BATTERY_4V8, AM_BATTERY_4V9, AM_BATTERY_FULL } AM_batteryState_t;

Timezone hander

AudioMoth applications can provide a time zone to the ensure that the timestamps in the FAT file system are in the appropriate local time.

extern void AudioMoth_timezoneRequested(int8_t *timezone);

Interrupt Handlers

AudioMoth applications are required to handle a number of interrupts. The simplest of these is an interrupt that triggers whenever the switch position is changed.

extern void AudioMoth_handleSwitchInterrupt(void);

Depending on how the microphone is configured the AudioMoth application may need to handle interrupts on the completion of each microphone ADC conversion.

extern void AudioMoth_handleMicrophoneInterrupt(int16_t sample);

Alternatively AudioMoth can be configured to transfer microphone samples directly to memory under direct memory access (DMA). An interrupt is triggered each time either the primary or secondary buffer is filled. The default operation mode is a ping-pong buffer, in which case the interrupt does not have to set nextBuffer. However, if other buffer configurations are required, nextBuffer should be set to the start address of the next buffer to fill.

extern void AudioMoth_handleDirectMemoryAccessInterrupt(bool isPrimaryBuffer, int16_t **nextBuffer);

USB Message Handlers

The AudioMoth library automatically handles a number of USB messages. These include setting the time, requesting the time, requesting the battery state, and requesting the unique ID of the device. Applications can define their own USB message formats in addition to these and must handle the following two requests.

extern void AudioMoth_usbApplicationPacketRequested(uint32_t messageType, uint8_t *transmitBuffer, uint32_t size);

extern void AudioMoth_usbApplicationPacketReceived(uint32_t messageType, uint8_t *receiveBuffer, uint8_t *transmitBuffer, uint32_t size);

USB Device Initialisation

The first thing that AudioMoth applications should do is call AudioMoth_initialise to set up the hardware and configure the clocks.

void AudioMoth_initialise(void);

To reduce energy consumption, it is common for AudioMoth applications to use the real time clock to enter a power-down state between activities. Applications can use 'AudioMoth_isInitialPowerUp' to determine whether the device has just powered up from one of these power-down periods, or from an external reset (due to initially fitting batteries or a watchdog reset).

bool AudioMoth_isInitialPowerUp(void);

Clock control

AudioMoth can use a range of different clock sources. The most accurate is the external 48MHz crystal that can be enabled, selected or disabled, using the functions below. This is enabled and selected automatically by the AudioMoth_initialise function.

void AudioMoth_enableHFXO(void);

void AudioMoth_selectHFXO(void);

void AudioMoth_disableHFXO(void);

AudioMoth also supports an internal RC oscillator which can be operated in six different frequency bands. These are enabled, selected and disabled, using the functions below. Note that when changing clock source, it is necessary to select the new clock source, before disabling the existing one.

void AudioMoth_enableHFRCO(AM_clockFrequency_t frequency);

void AudioMoth_selectHFRCO(void);

void AudioMoth_disableHFRCO(void);

The internal RC oscillator can be tuned over a small range (typically +/- 5%) and can be calibrated against the external 48MHz crystal. This can be performed automatically using the function below.

void AudioMoth_calibrateHFRCO(uint32_t frequency);

Calibration of the internal RC oscillator is most often required to achieve specific microphone sample rates. The frequency of any particular frequency band can be retrieved using the AudioMoth_getClockFrequency function.

uint32_t AudioMoth_getClockFrequency(AM_clockFrequency_t frequency);

External SRAM Control

The external SRAM may not be necessary in all applications and is disabled and powered down by default. It may be enabled and then disabled as required.

void AudioMoth_enableExternalSRAM(void);

void AudioMoth_disableExternalSRAM(void);

Microphone samples

The microphone of the AudioMoth is powered up and enabled using the function below. This function requires the gain (0 - 4) to be specified, the divider that is applied to the main clock to generate the ADC clock, the number of acquisition cycles over which the ADC collects data, and the hardware oversampling rate.

void AudioMoth_enableMicrophone(uint32_t gain, uint32_t clockDivider, uint32_t acquisitionCycles, uint32_t oversampleRate);

The latter three arguments, along with the main clock frequency, determines the maximum possible sampling rate of the device - sampleRate = (2 + (acquisitionCycles + 12) * overSampleRate) / (frequency / clockDivider). A utility function calculates this within applications.

uint32_t AudioMoth_calculateSampleRate(uint32_t frequency, uint32_t clockDivider, uint32_t acquisitionCycles, uint32_t oversampleRate);

The transfer of microphone samples can then be configured to use either direct interrupts on the completion of each ADC conversion, or using direct memory transfer to transfer a number of samples into memory. The latter uses ping-pong buffering by default and is initialised with pointers to the primary and secondary buffers, and the number of samples in each transfer (maximum 1024).

void AudioMoth_initialiseMicrophoneInterupts(void);

void AudioMoth_initialiseDirectMemoryAccess(int16_t *primaryBuffer, int16_t *secondaryBuffer, uint16_t numberOfSamples);

The actual collection of microphone samples is started with the function below which uses a timer to generate samples at the specified sample rate.

void AudioMoth_startMicrophoneSamples(uint32_t sampleRate);

Finally, the microphone can be disabled and powered down using the function below.

void AudioMoth_disableMicrophone(void);

USB

The AudioMoth_handleUSB functions handles all communication with the host computer. The AudioMoth library automatically handles requests to set the time, read the time, read the battery state, and read the unique ID of the device. If the AudioMoth device is not connected to a USB host, it will enter a low-power state until it is reconnected. Function will return immediately if the switch is not in the 'USB' and will block until the switch moved away from 'USB'

void AudioMoth_handleUSB(void);

Backup Domain

AudioMoth provides an area of internal SRAM which is persistent across device power down. This can be accessed directly through the AM_EXTERNAL_SRAM_START_ADDRESS address, or through the two functions below.

uint32_t AudioMoth_retreiveFromBackupDomain(uint32_t register);

void AudioMoth_storeInBackupDomain(uint32_t register, uint32_t value);

Time

AudioMoth has a real time counter that can be set and read through the methods below. The real-time counter continues to run when the device is in powered down. A flag indicates whether the time has been set since the last device reset.

uint32_t AudioMoth_getTime(void);

bool AudioMoth_hasTimeBeenSet(void);

void AudioMoth_setTime(uint32_t time);

Watch Dog Timer

AudioMoth automatically runs a watch dog timer to prevent software hanging. If the watch dog timer is not fed every 60 seconds it will reset the device. In normal operation, when collecting microphone samples or interacting with USB, the AudioMoth library automatically feeds the watch dog timer. If the user application performs a very long operation it may be necessary to temporarily disable the watch dog timer or to feed it manually.

void AudioMoth_startWatchdog(void);

void AudioMoth_stopWatchdog(void);

void AudioMoth_feedWatchdog(void);

bool AudioMoth_hasWatchdogResetOccured(void);

Battery State Monitoring

The state of the AudioMoth battery can be accessed using the function below.

AM_batteryState_t AudioMoth_getBatteryState();

Switch Position Monitoring

The current state of the AudioMoth switch can be accessed using the function below.

AM_switchPosition_t AudioMoth_getSwitchPosition();

Busy delay

The function below performs a busy wait using a timer to give a precise time interval.

void AudioMoth_delay(uint16_t milliseconds);

Sleep and Power Down

To ensure minimum power consumption it is common to sleep the AudioMoth device whilst waiting for microphone samples to be available. This is achieved through a single function.

void AudioMoth_sleep();

The device may also be powered down. This is permanent and requires the cycling of the power (removing and refitting batteries) to wake again.

void AudioMoth_powerDown();

More useful is the ability to power down and automatically wake up after a number of seconds. This function uses the real-time counter and ensures that the power down energy consumption is in the order of 20 - 30 uA. The synchronised flag indicates whether the next wake-up should occur on the transition of the second counter, or if the device should be powered down for the full seconds seconds.

void AudioMoth_powerDownAndWake(uint32_t seconds, bool synchronised);

LED Control

The red and green LED can be controlled using the functions below.

void AudioMoth_setRedLED(bool state);

void AudioMoth_setBothLED(bool state);

void AudioMoth_setGreenLED(bool state);

File System

AudioMoth supports writing of any file type to the microSD card. The file system in enabled and disabled (including powering up and powering down the microSD card) with the two functions below.

bool AudioMoth_enableFileSystem();

void AudioMoth_disableFileSystem();

The library allows a new file to be opened (overwriting an existing file) and an existing file to be appended.

bool AudioMoth_openFile(char *filename);

bool AudioMoth_appendFile(char *filename);

It is also possible to move to any point within the file.

bool AudioMoth_seekInFile(uint32_t position);

Files are written to using the function below.

bool AudioMoth_writeToFile(void *bytes, uint16_t bytesToWrite);

If the file is not immediately closed, subsequent writes are buffered to ensure that the microSD card is written to in blocks of 512 bytes. Updating files with multiple small changes (closing the file each time) is inefficient as the microSD card can typically only update 512 byte pages and thus must repeatedly read and write to the same page.

bool AudioMoth_closeFile();

Existing closed files can also be renamed.

bool AudioMoth_renameFile(char *originalFilename, char *newFilename);
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.