/*
 * Copyright (c) 2016-2017 Satlab Aps <satlab@satlab.com>
 * All rights reserved. Do not distribute without permission.
 */

/**
 * @file polaris_adsb_sample.h
 *
 * This file provides functions to is used to read raw sample data from the
 * Polaris sample buffer via CSP. The source can currently only be short (fixed
 * length) bursts of full spectrum data. 
 *
 * The number of captured samples must be 8192 for
 * SL_POLARIS_ADSB_SAMPLEBUF_SOURCE_RAW source.
 *
 * Samples are 32-bit words consisting of 16-bit IQ channels.
 *
 * @note The sample commands write data into external SDRAM, which is
 * automatically enabled and kept powered on after sampling. This results in a
 * higher power consumption after the first sample request is received.
 */

#ifndef _SL_POLARIS_ADSB_CLIENT_SAMPLE_H_
#define _SL_POLARIS_ADSB_CLIENT_SAMPLE_H_

#include <unistd.h>
#include <stdint.h>

/**
 * @brief Read data from sample buffer
 *
 * The Polaris device will send the samples via CSP to the requesting node
 * address immediately after request.
 *
 * @param node		CSP address of the Polaris node.
 * @param timeout	Timeout of the command in milliseconds.
 * @param source	Sample source identifier. Must be:
 *			SL_POLARIS_ADSB_SAMPLEBUF_SOURCE_RAW
 * @param out		Pointer to output data array.
 * @param outlen	Size of the output array in bytes (must be 4x number of samples).
 *
 * @returns 0 on success, and a negative error code on error.
*/
int sl_polaris_adsb_sample_read(uint8_t node, uint32_t timeout, uint8_t source, uint32_t *out, size_t outlen);

/**
 * @brief Save sample buffer data
 *
 * This function is used to store raw sample data on the Polaris device for
 * later download using BTP.
 *
 * @param node		CSP address of the Polaris node.
 * @param timeout	Timeout of the command in milliseconds.
 * @param source	Sample source identifier. Must be:
 * 			SL_POLARIS_ADSB_SAMPLEBUF_SOURCE_RAW
 * @param dest 		Destination identifier. Must be one of:
 * 			SL_POLARIS_ADSB_SAMPLEBUF_DEST_CSP
 * 			SL_POLARIS_ADSB_SAMPLEBUF_DEST_MEM
 * 			SL_POLARIS_ADSB_SAMPLEBUF_DEST_SDCARD
 * @param samples 	Number of samples to store.
 * @param id 		Identification number of sample. Samples stored to the
 * 			SD-card will be named s<id>.bin, e.g. s1000.bin for
 * 			sample ID 1000.
 *
 * @returns 0 on success, and a negative error code on error.
 */
int sl_polaris_adsb_sample_store(uint8_t node, uint32_t timeout, uint8_t source, uint8_t dest, size_t samples, uint32_t id);

#endif /* _SL_POLARIS_ADSB_CLIENT_SAMPLE_H_ */
