picapi.h File Reference

---

Detailed Description

AXIS PIC API header file.

Author:

Mike Ballinger

Date:

11/1/05

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	FALSE   0
#define	TRUE   1
#define	DIGITAL_INPUT   0
	Configure pin as a digital input.
#define	ANALOGUE_INPUT   1
	Configure pin as an analogue input.
#define	PIC_SUCCESS   0
	Successful operation.
#define	PIC_UNKNOWNERROR   -1
	Unknown error.
#define	PIC_FILEERROR   -2
	PIC file handle error.
#define	PIC_HDRMISMATCH   -3
	Header checksum mismatch.
#define	PIC_DATAMISMATCH   -4
	Data packet checksum mismatch.
#define	PIC_PARAMERROR   -5
	Invalid parameters.
Functions
int	PIC_Initialise (void)
	Initialises communications between the AXIS and the PIC. This must be called before using any PIC API functions.
void	PIC_Close (int fdPIC)
	Closes communications between the AXIS and the PIC. This should be called at the end of your program after all PIC API calls have been made.
int	PIC_ReadFirmwareVersion (int fdPIC, int *version)
	Obtains the PIC firmware version.
int	PIC_ReadRTC (int fdPIC, time_t *rtc)
	Reads the real time clock.
int	PIC_SetRTC (int fdPIC, time_t rtc)
	Sets the real time clock.
int	PIC_ReadPowerOffTime (int fdPIC, time_t *powerOffTime)
	Obtains the last PIC power-off time.
int	PIC_ReadPowerOnTime (int fdPIC, time_t *powerOffTime)
	Obtains the last PIC power-on time.
int	PIC_ReadAnalogueInput (int fdPIC, int adcPort, int *value)
	Perform an A/D conversion on the specified analogue input. Each port has a resolution of 10 bits equating to an integer range of 0 to 1023.
int	PIC_ReadSwitches (int fdPIC, int *switches)
	Returns the current state of the 8 input switches.
int	PIC_ClearLog (int fdPIC)
	Empties the power-off switch logger.
int	PIC_GetLogEntry (int fdPIC, int *valid, time_t *rtc, int *switches)
	Obtains the next switch log entry. Every entry contains the switch position in addition to the PIC time at which the switch event took place.
int	PIC_DeleteLogEntry (int fdPIC, int *deleteOK)
	Deletes the oldest power-off switch log entry.
int	PIC_ReadWatchdogResetFlag (int fdPIC, int *flag)
	Checks whether a watchdog reset has occurred. As soon as this flag is read then it is automatically cleared.
int	PIC_ReadPowerOnResetFlag (int fdPIC, int *flag)
	Checks whether a power-on reset has occurred. As soon as this flag is read then it is automatically cleared.
int	PIC_ReadBrownOutResetFlag (int fdPIC, int *flag)
	Checks whether a brown out reset has occurred. As soon as this flag is read then it is automatically cleared.
int	PIC_ReadOscillatorFailureFlag (int fdPIC, int *flag)
	Checks whether an oscillator failure has occurred. As soon as this flag is read then it is automatically cleared.
int	PIC_ReadLogBufferOverflowFlag (int fdPIC, int *flag)
	Checks whether a power off switch log overflow has occurred. As soon as this flag is read then it is automatically cleared.
int	PIC_BatteryFastCharge (int fdPIC, int fastCharge)
	Controls battery fast charge. Please note that it is not recommended to leave the battery fast-charging for long periods of time.
int	PIC_BatteryReadVoltage (int fdPIC, int *batteryVoltage)
	Reads the current battery voltage. This is a 10-bit value with a corresponding range of 0 to 1023.
int	PIC_BatteryReadMaxRef (int fdPIC, int *maxRef)
	Reads the maximum battery reference voltage when in low power mode. This is a 10-bit value with a corresponding range of 0 to 1023.
int	PIC_BatteryReadMinETXVoltage (int fdPIC, int *minETXVoltage)
	Reads the minimum ETX voltage. This is a 10-bit value with a corresponding range of 0 to 1023.
int	PIC_ConfigureRA2InputType (int fdPIC, int type)
	Configures RA2 as either an analogue or a digital input. Please note that when configured as an analogue input then the corresponding multiplexed switch input bits will be masked out.
int	PIC_ConfigureRA4InputType (int fdPIC, int type)
	Configures RA4 as either an analogue or a digital input. Please note that when configured as an analogue input then the corresponding multiplexed switch input bits will be masked out.

---

Function Documentation

int PIC_BatteryFastCharge (  int  fdPIC, int  fastCharge )

Controls battery fast charge. Please note that it is not recommended to leave the battery fast-charging for long periods of time. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). fastCharge  - If this value is 1 then battery fast charge will be turned on, and if 0 then fast charge will be turned off. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_BatteryReadMaxRef (  int  fdPIC, int *  maxRef )

Reads the maximum battery reference voltage when in low power mode. This is a 10-bit value with a corresponding range of 0 to 1023. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *maxRef  - The maximum battery reference voltage is stored here. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_BatteryReadMinETXVoltage (  int  fdPIC, int *  minETXVoltage )

Reads the minimum ETX voltage. This is a 10-bit value with a corresponding range of 0 to 1023. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *minETXVoltage  - The minimum ETX voltage is stored here. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_BatteryReadVoltage (  int  fdPIC, int *  batteryVoltage )

Reads the current battery voltage. This is a 10-bit value with a corresponding range of 0 to 1023. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *batteryVoltage  - The current battery voltage is stored here. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ClearLog (  int  fdPIC  )

Empties the power-off switch logger. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). Returns: Success/error code. See list of PIC API Return Codes.

void PIC_Close (  int  fdPIC  )

Closes communications between the AXIS and the PIC. This should be called at the end of your program after all PIC API calls have been made. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). Returns: None

int PIC_ConfigureRA2InputType (  int  fdPIC, int  type )

Configures RA2 as either an analogue or a digital input. Please note that when configured as an analogue input then the corresponding multiplexed switch input bits will be masked out. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). type  - Defines whether the input will be analogue or digital. Two values have been defined in picapi.h for this: ANALOGUE_INPUT and DIGITAL_INPUT. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ConfigureRA4InputType (  int  fdPIC, int  type )

Configures RA4 as either an analogue or a digital input. Please note that when configured as an analogue input then the corresponding multiplexed switch input bits will be masked out. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). type  - Defines whether the input will be analogue or digital. Two values have been defined in picapi.h for this: ANALOGUE_INPUT and DIGITAL_INPUT. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_DeleteLogEntry (  int  fdPIC, int *  deleteOK )

Deletes the oldest power-off switch log entry. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *deleteOK  - This value contains the delete result. If it is zero then the delete entry was unsuccessful (probably because the buffer was empty) otherwise the delete was successful. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_GetLogEntry (  int  fdPIC, int *  valid, time_t *  rtc, int *  switches )

Obtains the next switch log entry. Every entry contains the switch position in addition to the PIC time at which the switch event took place. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *valid  - The value stored in this variable will indicate whether the obtained log entry is valid. If this is 0 then it is not valid (the log buffer is empty) otherwise there will be a valid entry. *rtc  - The RTC value at the point of the switch event will be stored here. *switches  - The switch state will be stored here. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_Initialise (  void   )

Initialises communications between the AXIS and the PIC. This must be called before using any PIC API functions. Date: 11/1/05 Author: Mike Ballinger Parameters: None  Returns: None

int PIC_ReadAnalogueInput (  int  fdPIC, int  adcPort, int *  value )

Perform an A/D conversion on the specified analogue input. Each port has a resolution of 10 bits equating to an integer range of 0 to 1023. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). adcPort  - Analogue port to read. Valid ports are 0, 1 and 2. *value  - Pointer to an integer where the analogue value will be stored. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadBrownOutResetFlag (  int  fdPIC, int *  flag )

Checks whether a brown out reset has occurred. As soon as this flag is read then it is automatically cleared. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *flag  - Contains the state of the flag - if zero then the flag is clear, otherwise the flag is set. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadFirmwareVersion (  int  fdPIC, int *  version )

Obtains the PIC firmware version. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *version  - Pointer to an integer where the PIC firmware version will be stored. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadLogBufferOverflowFlag (  int  fdPIC, int *  flag )

Checks whether a power off switch log overflow has occurred. As soon as this flag is read then it is automatically cleared. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *flag  - Contains the state of the flag - if zero then the flag is clear, otherwise the flag is set. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadOscillatorFailureFlag (  int  fdPIC, int *  flag )

Checks whether an oscillator failure has occurred. As soon as this flag is read then it is automatically cleared. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *flag  - Contains the state of the flag - if zero then the flag is clear, otherwise the flag is set. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadPowerOffTime (  int  fdPIC, time_t *  powerOffTime )

Obtains the last PIC power-off time. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *powerOffTime  - Pointer to a variable of type "time_t" where the power-off time will be stored. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadPowerOnResetFlag (  int  fdPIC, int *  flag )

Checks whether a power-on reset has occurred. As soon as this flag is read then it is automatically cleared. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *flag  - Contains the state of the flag - if zero then the flag is clear, otherwise the flag is set. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadPowerOnTime (  int  fdPIC, time_t *  powerOnTime )

Obtains the last PIC power-on time. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *powerOnTime  - Pointer to a variable of type "time_t" where the power-on time will be stored. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadRTC (  int  fdPIC, time_t *  rtc )

Reads the real time clock. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *rtc  - Pointer to a variable of type "time_t". The RTC will be stored here. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadSwitches (  int  fdPIC, int *  switches )

Returns the current state of the 8 input switches. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *switches  - Pointer to an integer where the switch states will be stored. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_ReadWatchdogResetFlag (  int  fdPIC, int *  flag )

Checks whether a watchdog reset has occurred. As soon as this flag is read then it is automatically cleared. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). *flag  - Contains the state of the flag - if zero then the flag is clear, otherwise the flag is set. Returns: Success/error code. See list of PIC API Return Codes.

int PIC_SetRTC (  int  fdPIC, time_t  rtc )

Sets the real time clock. Date: 11/1/05 Author: Mike Ballinger Parameters: fdPIC  - The PIC handle. This is obtained after a call to PIC_Initialise( ). rtc  - Variable containing the required PIC time. Returns: Success/error code. See list of PIC API Return Codes.

---