The NIST Smart Space Laboratory Web Site

Next: 5 The box. Up: 4 The softwares on Previous: 4.2 The oscilloscope Contents

Subsections

4.3 The library

This library can be found in the zipped cvs on the website http://www.nist.gov/smartspace/nsfs.html. The code is located in the folder: smartspace/development/audio/audiocapture/sources/mk3lib

4.3.1 mk3array_create

The function creates and returns an opaque handler for a 'mk3array' but does not initialize the connection.

mk3array* mk3array_create(int megabytes, int requested_data_frames_per_buffer, mk3error *err);

arg 1 : int the request amount of memory to use for the internal storage of the collected data (0 will make the program use its default value)
arg 2 : int when receiving data, this value allow the user to request a certains amount of data frames to be delivered to the 'get' functions
arg 3 : mk3error* in order to set the error state of the function (if any)
return: mk3array* newly created 'mk3array' (to be deleted using 'mk3array_delete')

4.3.2 mk3array_comminit

Create the communication socket between the local system and the mk3.

void mk3array_comminit(mk3array *it, const char *dip, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : const char* the IP address of the mk3 to connect to
arg 3 : mk3error* error state of function (if any)
return: void

4.3.3 mk3array_ask_speed

Query the mk3 (if no value was set by the user) to check the current value of the sampling rate (== capture 'speed')

int mk3array_ask_speed(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int one of 'mk3array_speed_22k' or 'mk3array_speed_44k'

4.3.4 mk3array_set_speed

Set the mk3 sampling rate

void mk3array_set_speed(mk3array *it, int speed, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : int one of 'mk3array_speed_22k' or 'mk3array_speed_44k'
arg 3 : mk3error* error state of function (if any)
return: void

4.3.5 mk3array_ask_slave

Query the mk3 (if no value was set by the user) to check the current value of the "slave" mode ("true", the mk3 clock is slave to an external clock, ...)

int mk3array_ask_slave(mk3array *it, mk3error *err)

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int one of 'mk3_true' or 'mk3_false'

4.3.6 mk3array_set_slave

Set the "slave" mode (warning: can not check that there is an external clock)

void mk3array_set_slave(mk3array *it, int slave, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : int one of 'mk3_true' or 'mk3_false'
arg 3 : mk3error* error state of function (if any)
return: void

4.3.7 mk3array_ask_id

Return the value of the 'id' of the mk3 (requested during comminit)

int mk3array_ask_id(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int

4.3.8 mk3array_ask_promnb

Set 'arg 2' of mk3array with the value of the 'prom_nb' (requested during comminit)

void mk3array_ask_promnb(mk3array *it, char *promnb, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : char* address of a char[9] (at least: 8 for info + '')
arg 3 : mk3error* error state of function (if any)
return: void

4.3.9 mk3array_initparams

Check that 'speed' and 'slave' are set then advance automaton

void mk3array_initparams(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: void

Set 'speed' and 'slave', then advance automaton. This is useful as it allows to initialize all the required parameters in one function. Mostly used when one knows the settings under which the capture will be performed. Note: wp = with parameters

void mk3array_initparams_wp(mk3array *it, int speed, int slave, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : int one of 'mk3array_speed_22k' or 'mk3array_speed_44k'
arg 3 : int one of 'mk3_true' or 'mk3_false'
arg 4 : mk3error* error state of function (if any)
return: void

4.3.11 mk3array_fix_drop_X_first_frames

Set the internal value for dropping a certain number of frames.

void mk3array_fix_drop_X_first_frames(mk3array *it, int X, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : int X value (in number of samples)
arg 3 : mk3error* error state of function (if any)
return: void

4.3.12 mk3array_display_warnings

Set the internal value for printing to 'stderr' when an specific situation is encountered (buffer overflow, lost packets)

void mk3array_display_warnings(mk3array *it, int truefalse, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : int one of 'mk3_true' or 'mk3_false'
arg 3 : mk3error* error state of function (if any)
return: void

4.3.13 mk3array_normalize

IF used, this function will force a normalization procedure to be applied on the captured data using data created for this particular microphone array by the mean/standard deviation file creator.

void mk3array_normalize(mk3array *it, file* mean_fd, file* stdev_fd, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : file* file handle for the 'mean' correction information
arg 3 : file* file handle for the 'standard deviation ' information
arg 4 : mk3error* error state of function (if any)
return: void

4.3.14 mk3array_capture_on

Starts data capture on the mk3

void mk3array_capture_on(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: void

4.3.15 mk3array_wait_capture_started

Blocking opeation: wait for capture 'status' to be set before returning

void mk3array_wait_capture_started(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* 'mk3error' handle
return: void

4.3.16 mk3array_get_databuffer

Get the next available databuffer (blocking)

void mk3array_get_databuffer(mk3array *it, char *databuffer, struct timespec *timestamp, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : char* pointer to the "data buffer" location in which to copy the data
arg 3 : timespec* pointer to a localy created 'timespec' that will contain the timespec detailling the capture time of the requested buffer
arg 4 : mk3error* error state of function (if any)
return: void

4.3.17 mk3array_get_databuffer_nonblocking

Get the next available databuffer (non-blocking), and move to cursor to next.

int mk3array_get_databuffer_nonblocking(mk3array *it, char *db, struct timespec *ts, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : char* pointer to the "data buffer" location in which to copy the data
arg 3 : timespec* pointer to a localy created 'timespec' that will contain the timespec detailling the capture time of the requested buffer (a 'null' value means do not return the corresponding timestamp)
arg 4 : mk3error* error state of function (if any)
return: int 'mk3_false' if no data was read / 'mk3_true' otherwise

4.3.18 mk3array_get_current_databuffer_timestamp

Get the next available timestamp (blocking), but do not consider the databuffer as read (one can either 'skip' or 'get' it there after)

void mk3array_get_current_databuffer_timestamp(mk3array *it, struct timespec *ts, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : timespec* pointer to a localy created 'timespec' that will contain the timespec detailling the capture time of the requested buffer
arg 3 : mk3error* error state of function (if any)
return: void

4.3.19 mk3array_skip_current_databuffer

Consider the next available databuffer read and move cursor to next.

void mk3array_skip_current_databuffer(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: void

4.3.20 mk3array_check_databuffer_overflow

Check if an ring buffer overflow occured for 'databuffer' access

int mk3array_check_databuffer_overflow(mk3array* it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int 'mk3_false' or 'mk3_true' dependent on overflow of internal structure

4.3.21 mk3array_check_lostdataframes

Return an 'int' containing the total number of data frames lost since the begining of the capture (reminder: 1 network frame = 5 data frames)

int mk3array_check_lostdataframes(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int total number of data frames lost so far

4.3.22 mk3array_check_capture_ok

Check that no error are occuring in the capture process

int mk3array_check_capture_ok(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: int 'mk3_true' if capture ok, 'mk3_false' otherwise

4.3.23 mk3array_capture_off

Stops data capture on the mk3

void mk3array_capture_off(mk3array *it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: void

4.3.24 mk3array_delete

The function frees memory used by the 'mk3array'

void mk3array_delete(mk3array* it, mk3error *err);

arg 1 : mk3array* 'mk3array' handle
arg 2 : mk3error* error state of function (if any)
return: void

4.3.25 How to use it

An example can be found in mk3cap folder.

The normal course of action of the program should be to call these functions in sequence:

1: mk3array_create
2: mk3array_comminit
3: mk3array_initparams
4: mk3array_capture_on
5: mk3array_get_databuffer
6: mk3array_capture_off
7: mk3array_delete

Next: 5 The box. Up: 4 The softwares on Previous: 4.2 The oscilloscope Contents

Cedrick Rochet 2005-09-21

Created on 2008-06-18 by Antoine Fillinger - Last updated on 2008-11-23 by Antoine Fillinger