Commit d8941382 authored by Colin González's avatar Colin González
Browse files

Prevent adding ISIS proprietary software to the repo

parent d04ac7de
# ISIS
hal
# Emacs
# -*- mode: gitignore; -*-
......
/*!
* @file ADC.h
* @brief Driver for reading Analog data (including OBC board temperature) using the ADC.
* @date Feb 26, 2013
* @author Akhil Piplani
*/
#ifndef ADC_H_
#define ADC_H_
#include <freertos/FreeRTOS.h>
#include <at91/commons.h>
#include "hal/boolean.h"
/*!
* The number of buffer elements in the circular buffer created by the ADC driver.
* This buffer is used to store the ADC samples. Using a circular buffer here allows
* the ADC driver to be samples into one element of the buffer while the application
* reads from another element.
*/
#define ADC_CIRCULAR_BUFFER_ELEMENTS 4
/*!
* Reference voltage used for the ADC. This can be used to convert the raw ADC output
* to milliVolts. The following formulae apply: \n
* @verbatim
* For 10-bit resolution:\n
* milliVolts = ((ADC_REFERENCE_VOLTAGE * rawValue)/0x3FF)\n
* For 8-bit resolution:\n
* milliVolts = ((ADC_REFERENCE_VOLTAGE * rawValue)/0xFF)\n
* @endverbatim
*/
#define ADC_REFERENCE_VOLTAGE 2500
typedef struct _ADCparameters {
unsigned int sampleRate; //!< Sample rate in Hz. Limits: Minimum 4030Hz, Maximum 75000Hz(10-bit resolution) or 250000Hz(8-bit resolution)
Boolean resolution10bit; //! Set to TRUE for 10-bit ADC resolution and FALSE for 8-bit ADC resolution.
/*!
* Number of channels to be sampled. Valid values are 1, 2, 3, 4, 8. Values of 5, 6 or 7 are not allowed.
* This is because ADC channels are doubled from 4 to 8 using an external multiplexer.
* Therefore when >4 channels are sampled, all channels are enabled at the ADC.
*/
unsigned int channels;
/*!
* Number of samples to be stored in a buffer for this driver for each channel.
* As DMA is used for saving the ADC samples, a larger value here would lead to fewer
* interrupts upon completion of a DMA transfer.\n
*
* It is recommended to use a value of 2048 here.
* If 10-bit resolution is used, samplesInBufferPerChannel * channels should be less than 32768
* If 8-bit resolution is used, samplesInBufferPerChannel * channels should be less than 65536
*/
unsigned int samplesInBufferPerChannel;
/*!
* Function that will be called by the Interrupt Service Routine of the ADC driver.
* A call to this function indicated reception of new ADC samples and a pointer to
* these is passed as a parameter.
* This function should be fast as it will be called from an ISR.
*
* @param adcSamples Pointer to the latest ADC samples buffer. \n
* Size of this buffer in bytes is: \n
* 10-bit resolution: channels * samplesInBufferPerChannel * 2 \n
* 8-bit resolution: channels * samplesInBufferPerChannel \n
*
* The user should cast this pointer to (unsigned char*) if 8-bit resolution is used
* and to (unsigned short*) if 10-bit resolution is used.
*
* Let SnCm mean sample-number-n for channel-number-m.
* Then the samples in the buffer are arranged in the following manner: \n
* S0C0, S0C1, S0C2, ... , S0CM, S1C0, S1C1....... SNCM.
*/
void (*callback)(SystemContext context, void* adcSamples);
} ADCparameters;
/*!
* Converts a raw 10-bit ADC sample to millivolts.
* @param adcRawSample Raw 10-bit ADC sample.
* @return The converted ADC sample in millivolts.
*/
unsigned int ADC_ConvertRaw10bitToMillivolt( unsigned short adcRawSample );
/*!
* Converts a raw 8-bit ADC sample to millivolts.
* @param adcRawSample Raw 8-bit ADC sample.
* @return The converted ADC sample in millivolts.
*/
unsigned int ADC_ConvertRaw8bitToMillivolt( unsigned char adcRawSample );
/*!
* Initializes the ADC driver and begins a single shot acquisition of 10-bit ADC samples for all 8 channels.
* @param adcSamples Pointer to an array which will contain the sampled ADC data.
* @return -2 when input buffer is NULL, -1 when ADC is busy with continuous mode, 0 on success.
*/
int ADC_SingleShot( unsigned short adcSamples[8] );
/*!
* Initializes the ADC driver and begins periodically storing the ADC samples in a buffer.
* A callback is called each time a set of ADC samples is buffered.
* @see ADCparameters
* @param params ADCparameters structure containing all the parameters required to properly initialize the driver.
* @return -2 when input parameters are invalid, -1 when memory allocation fails, 0 on success.
*/
int ADC_start(ADCparameters params);
/*!
* De-initializes the ADC driver and stops the collection of ADC samples.
*/
void ADC_stop(void);
#endif /* ADC_H_ */
/*!
* @file I2C.h
* @brief I2C master communication driver.
* @warning User may not change the entries in this header file. Values such as
* define preprocessor directives are for information and not for configuration.
* @date Oct 26, 2012
* @author Akhil Piplani
*/
#ifndef I2C_H_
#define I2C_H_
#include <at91/commons.h>
#include <freertos/FreeRTOS.h>
#include <freertos/semphr.h>
#include <freertos/task.h>
/*!
* State of the Driver.
*/
typedef enum _I2CdriverState {
idle_i2cState = 0x00, //!< idle_i2cState
uninitialized_i2cState = 0x33,//!< uninitialized_i2cState
write_i2cState = 0x55, //!< write_i2cState
read_i2cState = 0xAA, //!< read_i2cState
error_i2cState = 0xFF //!< error_i2cState
} I2CdriverState;
/*!
* Possible directions of an I2C transfer.
*/
typedef enum _I2Cdirection {
write_i2cDir = 0x55,//!< write_i2cDir
read_i2cDir = 0xAA,//!< read_i2cDir
writeRead_i2cDir = 0xFF //!< writeRead_i2cDir
} I2Cdirection;
/*!
* Status of a transfer being processed by the I2C driver.
*/
typedef enum _I2CtransferStatus {
done_i2c = 0, //!< done_i2c
pending_i2c = 1, //!< pending_i2c
writeDone_i2c = 2, //!< writeDone_i2c
writeDoneReadStarted_i2c = 3,//!< writeDoneReadStarted_i2c
writeError_i2c = 4, //!< writeError_i2c
readError_i2c = 5, //!< readError_i2c
timeoutError_i2c = 6, //!< timeoutError_i2c
error_i2c = 7 //!< error_i2c
} I2CtransferStatus;
/*!
* A generic descriptor for an I2C transfer where every type of parameter of the transfer can be specified.
* This is passed to I2C_queueTransfer.
*/
typedef struct _I2CgenericTransfer {
unsigned int slaveAddress; //!< Address of the slave where to make the transfer.
I2Cdirection direction; //!< Direction of the I2C transfer.
unsigned int writeSize; //!< Number of bytes to be written to the I2C slave (used for write_i2cDir and writeRead_i2cDir).
unsigned int readSize; //!< Number of bytes to be read from the I2C slave (used for read_i2cDir and writeRead_i2cDir).
unsigned char *writeData; //!< Memory location of the data to be written to the I2C slave (used for write_i2cDir and writeRead_i2cDir).
volatile unsigned char *readData; //!< Memory location to store the data read from the I2C slave (used for read_i2cDir and writeRead_i2cDir).
portTickType writeReadDelay; //!< A delay inserted between writing to an I2C slave and reading back from it (used only for writeRead_i2cDir).
I2CtransferStatus *result; //!< The driver will store the result of a transfer in this location at the end of the transfer.
// The following members are not inputs for blocking transfers.
xSemaphoreHandle semaphore; //!< This will be passed to the callback. If the task is blocking on this semaphore for the transfer to complete, the callback can release it to unblock the task.
void (*callback)(SystemContext context, xSemaphoreHandle sem); //!< Name of a function that will be called when the transfer is complete.
// The following members are only used internally by the driver.
portTickType writeCompleteTime; //!< Internal use by driver
xTaskHandle callingTaskHandle; //!< Internal use by driver
} I2CgenericTransfer;
/*!
* A descriptor for an I2C transfer that is passed to I2C_writeRead.
*/
typedef struct _I2CwriteReadTransfer {
unsigned int slaveAddress; //!< Address of the slave where to make the transfer.
unsigned int writeSize; //!< Number of bytes to be written to the I2C slave.
unsigned int readSize; //!< Number of bytes to be read from the I2C slave.
unsigned char *writeData; //!< Memory location of the data to be written to the I2C slave.
volatile unsigned char *readData; //!< Memory location to store the data read from the I2C slave.
portTickType writeReadDelay; //!< A delay inserted between writing to an I2C slave and reading back from it.
} I2Ctransfer;
/*!
* Initializes the I2C driver.
* @param i2cBusSpeed_Hz Speed of the I2C bus in Hertz. (Minimum: 10000, Maximum 400000)
* @param i2cTransferTimeout Timeout for a byte to be transferred in 1/10th of a tick.
* @note When debugging the code use portMAX_DELAY to make this timeout infinite.
* Otherwise, stepping through code can trigger the I2C timeout.
* If this value is less than 1, the driver uses a timeout of 1.
* @return -3 if creating queues to handle transfers fails,
* -2 if Initializing the TWI peripheral fails,
* -1 if creating the task that consumes I2C transfer requests failed,
* 0 on success.
*/
int I2C_start(unsigned int i2cBusSpeed_Hz, unsigned int i2cTransferTimeout);
/*!
* Sets the timeout for a read or write transaction to complete.
* @param i2cTransferTimeout Timeout for a read or write transaction to complete in 1/10th of a tick.
* If this value is less than 1, the driver uses a timeout of 1.
* @note When debugging the code, use portMAX_DELAY to make this timeout infinite.
* Otherwise, stepping through code can trigger the I2C timeout.
*/
void I2C_setTransferTimeout(unsigned int i2cTransferTimeout);
/*!
* De-initializes the I2C driver.
*/
void I2C_stop(void);
/*!
* Blocks the bus, preventing any further transmissions on it until released. If there is a transmission
* ongoing, it will wait until *timeout* or the bus is released
* @param timeout Length of time to wait for current transmission to finish (portMAX_DELAY to wait forever)
* @return 0 on success, 1 if there was a timeout
*/
int I2C_blockBus(portTickType timeout);
/*!
* Release back the bus.
*/
void I2C_releaseBus(void);
/*!
* Writes data to a slave on the I2C bus using DMA.
* This is a blocking call. The task will be swapped out of context while the transfer is in progress.
* @param slaveAddress Address of the slave where to make the transfer.
* @param data Memory location of the data to be written to the I2C slave.
* @param size Number of bytes to be written to the I2C slave.
* @return -3 if creating a semaphore to wait for the transfer fails,
* -2 if the input transfer parameters are wrong or the driver is not initialized,
* -1 if queuing the transfer fails,
* 0 on success,
* 4 on write error,
* 6 on timeout error,
* 7 on general error.
* @note Negative values imply there was an initialization error,
* so the transfer was never attempted on the I2C bus,
* positive values mean a transfer was attempted on the I2C bus but failed.
* @note Positive error values correspond in value to the members of I2CtransferStatus.
*/
int I2C_write(unsigned int slaveAddress, unsigned char *data, unsigned int size);
/*!
* Reads data from a slave on the I2C bus using DMA.
* This is a blocking call. The task will be swapped out of context while the transfer is in progress.
* @param slaveAddress Address of the slave where to make the transfer.
* @param data Memory location to store the data read from the I2C slave. Must be able to store size bytes.
* @param size Number of bytes to be read from the I2C slave.
* @return -3 if creating a semaphore to wait for the transfer fails,
* -2 if the input transfer parameters are wrong,
* -1 if queuing the transfer fails,
* 0 on success,
* 5 on read error,
* 6 on timeout error,
* 7 on general error.
* @note Negative values imply there was an initialization error,
* so the transfer was never attempted on the I2C bus,
* positive values mean a transfer was attempted on the I2C bus but failed.
* @note Positive error values correspond in value to the members of I2CtransferStatus.
*/
int I2C_read(unsigned int slaveAddress, unsigned char *data, unsigned int size);
/*!
* Writes and then reads data to/from a slave on the I2C bus using DMA.
* This is a blocking call. The task will be swapped out of context while the transfer is in progress.
* @param tx Pointer to a I2CwriteReadTransfer structure that specifies the parameters for this transfer.
* @note If tx->readSize is zero but tx->writeSize is non-zero, this becomes a write transfer.
* Conversely, If tx->writeSize is zero but tx->readSize is non-zero, this becomes a read transfer.
* @return -3 if creating a semaphore to wait for the transfer fails,
* -2 if the input transfer parameters are wrong,
* -1 if queuing the transfer fails,
* 0 on success.
* 4 on write error,
* 5 on read error,
* 6 on timeout error,
* 7 on general error.
* @note Negative values imply there was an initialization error,
* so the transfer was never attempted on the I2C bus,
* positive values mean a transfer was attempted on the I2C bus but failed.
* @note Positive error values correspond in value to the members of I2CtransferStatus.
*/
int I2C_writeRead(I2Ctransfer *tx);
/*!
* Queues a transfer into the I2C driver. This is a non-blocking call.
* The driver goes through its internal queue and processes transfers using DMA.
* @param tx I2Ctransfer containing parameters for the transfer.
* @return -2 if the input transfer parameters are wrong,
* -1 if queuing the transfer fails,
* 0 on success.
*/
int I2C_queueTransfer(I2CgenericTransfer *tx);
/*!
* Returns the current state of the I2C driver.
* @return I2CdriverState.
*/
I2CdriverState I2C_getDriverState(void);
/*!
* Returns the status of the current transfer.
* @return I2CtransferStatus
*/
I2CtransferStatus I2C_getCurrentTransferStatus(void);
#endif /* I2C_H_ */
/*!
* @file I2Cslave.h
* @brief I2C slave communication.
* @date Feb 7, 2011
* @author Akhil Piplani
*/
#ifndef I2CCOMM_H_
#define I2CCOMM_H_
#include "hal/boolean.h"
#include <at91/commons.h>
#include <freertos/FreeRTOS.h>
/*!
* Size of the buffer used to store receive commands. Commands larger than this may cause problems.
* This size should not be too large either, as these buffers are stored on the small internal SRAM of the CPU to keep things fast.
* @note Customers should not modify this value, it will have no effect if the driver is provided as a library.
*/
#define I2C_SLAVE_RECEIVE_BUFFER_SIZE 512
/*!
* @brief Describes the I2C Slave Driver state.
*/
typedef enum _I2CslaveDriverState {
uninitialized_i2cSlaveDriverState = 0x00,//!< uninitialized_i2cSlaveDriverState
idle_i2cSlaveDriverState = 0x5A, //!< idle_i2cSlaveDriverState
slaveAcess_i2cSlaveDriverState = 0x55, //!< slaveAcess_i2cSlaveDriverState
read_i2cSlaveDriverState = 0xAA, //!< read_i2cSlaveDriverState
write_i2cSlaveDriverState = 0xFF //!< write_i2cSlaveDriverState
} I2CslaveDriverState;
/*!
* Information used by the driver to automatically receive a fixed number of
* bytes. Note, the number of bytes specified should not include the command.
* itself. Any command not in this list is treated as an invalid command.
*
* This driver expects the following I2C transaction format:\n
* 1) Every request for data from the I2C master is preceded by a command that describes what data is being requested.
* Therefore, an I2C slave never tries to write data on the I2C bus on its own.\n
* 2) Commands may or may not have a response.
*/
typedef struct _I2Cslave_CommandList {
unsigned char command; //!< Command code (first byte sent by the I2C master).
unsigned int commandParameterSize; //!< Number of bytes to read after receiving the command. If the command does not have any parameters, this should be 0.
Boolean hasResponse; //!< The user code replies to to this command with a response data packet i.e. I2Cslave_write is called in response to this command.
} I2CslaveCommandList;
/*!
*
* Sets up the I2C slave driver.
*
* @param address Address of the slave on the I2C bus.
* @param commandList Pointer to an array of I2CslaveCommandList structures which the driver
* queries to find out the number of bytes to automatically receive after receiving a certain command.
* @param commandListSize Number of commands in the above list.
* i.e. ((size of commandList array in bytes) / sizeof(I2CslaveCommandList))
*
* @return -5 when no command list is provided or its size is invalid or the address is not a 7-bit number,
* -4 if a commandParameterSize is too large (>=512),
* -3 if command codes in the list are not unique,
* -2 if memory allocation or starting tasks fails,
* -1 if pin configuration fails,
* 0 on success.
*
* @note The command codes in the commandList must be unique.
* @see I2CslaveCommandList
*/
int I2Cslave_start(unsigned char address, I2CslaveCommandList *commandList, unsigned int commandListSize);
/*!
* @brief Disables all I2C related interrupts and powers the TWI peripheral down.
*/
void I2Cslave_stop(void);
/*!
* @brief Writes data TO the master on the I2C bus.
* @param data Pointer to a location where the data to write is stored.
* @param size Number of bytes to transfer.
* @param timeout Number of milliseconds to wait for the transfer to complete. Use portMAX_DELAY to wait indefinitely.
*
* @return -3 if the driver has not been initialized,
* -2 if size is 0,
* -1 if timeout occurs while attempting to send data,
* otherwise the number of bytes written to the bus.
*
* @note If this value is positive but not equal to size, then the I2C-master terminated the transfer early with a NACK.
* @note If this function is called while a write transfer is in progress,
* it will wait for the previous transfer to complete before the current one is started.
* @note This function must always be called in response to a command from the I2C master.
*
* @note IMPORTANT: When the I2C master requests data, the driver will clock-stretch the I2C bus until this function is called.
* This allows you some time to send the data.\n
* However, there is a timeout on the clock-stretching of 200ms to avoid indefinite clock-stretching.
* If this timeout is reached, the driver will send 0xEE to the I2C master (indicating an error).
*
*/
int I2Cslave_write(unsigned char *data, unsigned long size, portTickType timeout);
/*!
* @brief Reads data from the I2C bus.
* In reality, the I2C slave can start receiving data as soon as it is initialized.
* This function simply waits until actual data is available and returns when the i2c master sends a command.
* @param[in,out] data A pointer to the location where the driver should store the received data. This buffer must be at least I2C_SLAVE_RECEIVE_BUFFER_SIZE bytes large.
* @return The number of bytes received as a command,
* if the return value is -1, the driver has not been initialized,
* if the return value is less than the number of bytes expected for the command code, the I2C-master terminated the transfer early.
*/
int I2Cslave_read(unsigned char *data);
/*!
* @brief Retrieves the current state of the I2C driver.
* @return driver state.
*/
I2CslaveDriverState I2Cslave_getDriverState(void);
/*!
* @brief Mutes the I2C interface from the higher layers but does not block the
* I2C bus.
*
* This function will cause the I2C driver to accept any amount of data from the
* master and reply with any amount of junk when requested by the master.
* This can be used to prevent the I2C bus from hanging when this subsystem is
* busy doing something that will make it unresponsive on the I2C bus.
*
* @param replyByte A byte that will be repeatedly transmitted when the
* master asks for data.
*
* @see I2Cslave_unMute()
*/
void I2Cslave_mute(unsigned char replyByte);
/*!
* @brief Unmutes the I2C interface. This function should be called after calling
* I2C_Mute when the subsystem has finished doing tasks that made it unavailable
* on the I2C bus.
*
* @see I2Cslave_mute()
*/
void I2Cslave_unMute(void);
#endif /* I2CCOMM_H_ */
/*!
* @file LED.h
* @brief LED control.
* @warning User may not change the entries in this header file. Values such as
* define preprocessor directives are for information and not for configuration.
* @date Feb 16, 2012
* @author Akhil Piplani
*/
#ifndef LED_H_
#define LED_H_
typedef enum _LED {
led_1 = 0,//!< led_1
led_2 = 1,//!< led_2
led_3 = 2,//!< led_3
led_4 = 3 //!< led_4
} LED;
/*!
* Initializes the LEDs by setting the corresponding pins as outputs on
* the PIO controller and setting the correct logic state of the pins.
*/
void LED_start(void);
/*!
* Makes the specified LED glow.
* @param led LED number that should glow.
*/
void LED_glow(LED led);
/*!
* Makes the specified LED dark.
* @param led LED number that should be dark.
*/
void LED_dark(LED led);
/*!
* Toggles the specified LED (Glow->Dark or Dark->Glow).
* @param led LED number that should toggle.
*/
void LED_toggle(LED led);
/*!
* Makes all LEDs switch on and off in a sequence.
* @param times Number of times the wave should be repeated.
*/
void LED_wave(unsigned int times);
/*!
* Makes all LEDs switch on and off in the reverse sequence as LED_wave.
* @param times Number of times the wave should be repeated.
*/
void LED_waveReverse(unsigned int times);
#endif /* LED_H_ */
/*!
* @file PWM.h
* @brief Pulse Width Modulation control.
* @warning User may not change the entries in this header file. Values such as
* define preprocessor directives are for information and not for configuration.
* @date Feb 27, 2013
* @author Akhil Piplani
*/
#ifndef PWM_H_
#define PWM_H_
/*!
* Maximum count value allowed at the Timer-Counter peripheral.
*/
#define TC_UPCOUNT_MAXVAL 0xFFFF
/*!
* Initializes the PWM driver that uses the Timer-Counter (TC) peripherals
* TC0, TC1 and TC2 and provides 6 PWM signals.
* The Timer will count from 0 up to maxUpCount and use the selected clock
* as an input to the timer module.
* The PWM lines are set when the counter reaches maxUpCount and cleared
* when the counter reaches the specified duty-cycle values.
* The combination of maxUpCount and timerClock affects the PWM resolution
* and frequency. \n
*
* pwm_frequency = timerClockSpeed / maxUpCount
*
* @param maxUpCount The maximum value up to which the timer will count.
* The maximum value of this input is 0xFFFF and minimum 1.
* @param timerClock The input clock of the timers to be used.
* The input value selects the timerClockSpeed by the following factors:
* 0 = BOARD_MCK/2, 1 = BOARD_MCK/8, 2 = BOARD_MCK/32, 3 = BOARD_MCK/128
* Other values are invalid. Normally, BOARD_MCK = 132MHz.
* Note that BOARD_MCK is not the processor clock, which is normally 400MHz.
* @return -1 if maxUpCount is greater than 0x3FF or maxUpCount is
* less than 1 or timerClock is greater than 3, \n
* 0 on success.
*
* @note Very low MaxUpCount will lead to a low resolution of the PWM duty-cycles.
*/
int PWM_start(unsigned short maxUpCount, unsigned int timerClock);
/*!
* Initializes the PWM driver that uses the Timer-Counter (TC) peripherals
* TC0, TC1 and TC2 and provides 6 PWM signals.
* This function will select the input clock automatically to achieve the
* desired PWM frequency.
* The Timer will count up from 0 to MaxUpCount.
* The PWM lines are set when the counter reaches maxUpCount and cleared
* when the counter reaches the specified duty-cycle values.
*
* @param frequency The desired frequency of the PWM signal. Maximum: BOARD_MCK/4
* minimum BOARD_MCK/(128*0xFFFF). Normally, BOARD_MCK = 132MHz.
* Note that BOARD_MCK is not the processor clock, which is normally 400MHz.
* @return Negative values signify error, positive values signify the MaxUpCount value.
* -1 is returned when the desired frequency cannot be achieved.
*
* @note Very low MaxUpCount will lead to a low resolution of the PWM duty-cycles.
*/
int PWM_startAuto(unsigned int frequency);
/*!
* Sets the duty cycle of 6 PWM channels based on the input.
* @param channels Pointer to an array of 6 unsigned integers containing DutyCycle values in percent.
* @return -1 if any of the input duty cycles is >100,
* 0 on success.
*/
int PWM_setDutyCycles(unsigned int *channels);
/*!
* Sets the duty cycle of 6 PWM channels based on the input.
* @param channels Pointer to an array of 6 unsigned integers containing
* DutyCycle values in raw form. The relation between raw inputs and percentage is:
* @verbatim
channelsRaw[i] = channels[i] * maxUpCount / 100;
* @endverbatim
* Here, maxUpCount (specified in PWM_start or returned by PWM_startAuto) is the
* maximum value the raw input should take.
* @return -1 if any of the input duty cycles is > MaxUpCount,
* 0 on success
*/
int PWM_setRawDutyCycles(unsigned short *channels);
/*!
* Sets all channel duty cycles to 0 percent.
*/
void PWM_setAllDutyCyclesZero(void);