1. Introduction

The software library supplied with the Compact Flash Data Logger allows the developer to interface to each of the hardware elements via function calls the library. This reduces the amount of development for the end user allowing you to concentrate on implementing your particular data acquisition and logging strategy.

Where possible the function names are the same as those used by Borland C, this allows the user to implement and test a large proportion of the functionality on a PC, using MSDOS or a MSDOS window under Windows, before porting the code to the Compact Flash Data Logger.

The user controls how the libraries operate by selected the appropriate data to be passed to the library functions or modifying constants in the library header files.

1.1. Nomenclature

CFDL – Compact Flash Data Logger

RTC – Real Time Clock

MSDOS – Microsoft Disk Operating System

EEPROM – Electrically Erasable Programmable Read Only Memory

2. Library Usage

 Interrupt functions.

 As the library has to take control of the interrupt function to call the relevant interrupt functions as required all the unused interrupts call associated functions, these have to be supplied by the users code, even if the function is empty. If the functions are omitted unresolved function errors would result. This allows the user to utilise the other features of the processor, unused timers etc.

OR

The user provides the interrupt function but it must be based on a template provided with the library so that library specific calls are preserved.

Wherever possible function naming the same as that used by Borland C.

How to use with PIC compiler

Which compiler and project set-up

3. Library functions

The functions contained in the library are grouped according to there association with each hardware element of the CFDL.

3.1. File management

The file management functions allow the user to create and write to files in a directory named DATA.  This DATA directory will be automatically created if not already present when a Compact Flash card is inserted into the CFDL. Both binary and ASCII files can be created.

3.2. Communications

The communication functions initialise the communications ports, and send and receive data. The size of the receive and transmit circular buffers set by modifying the constants UART1_TX_BUFFER_SIZE and UART1_RX_BUFFER_SIZE in the file urt1_drv.h. Note: - These constants must be set to a power of 2, otherwise the data may be overwritten.

The following functions are required in the interrupt service routine in order to service the communications port.

void Uart1TxHandler(void);

void Uart1RxHandler(void);

An identical set of functions are available for the second communications port for developmental use.  This port consists of a set of three wire points adjacent to the power supply select link.

3.3. Utility and Debug functions

For development and debugging purposes, there are some utility functions and communications routines which utilise the second serial port.  Note this is suitable for RS232 connections over short distances only.

3.4. Analogue inputs

The analogue input functions allow the user to control the sample rate and synchronisation and access to the ADC readings.  There are functions to setup and initialise the analogue inputs, as well as retrieve ascii strings representing the converted voltages.  The analogue input conversion process uses a function which is a state machine, it requires three cycles per conversion of each channel.  This allows the user to control the frequency of conversion by the frequency of the calls to this function. 

3.5. Digital input/output

The digital input/output functions allow the user to select the data direction and to read/set the ports as desired.  A development function is also included which toggles a selected digital output. 

3.6. Date and time

The date and time functions control the real time clock, the functions calls set or read the clock.  The date and time can be read either as encoded binary values or as Ascii strings, with separate strings for each of Year, Month, Date, Hour, Minute, Second. The file rtc_drv.h contains constants for encoded date and time, as well as the Ascii string variables. 

3.7. Detailed function description

The following section contains a detailed description of each of the functions giving their syntax, associated header file and any return value.

InitFile

Syntax
#include <file.h>
void InitFile( void );

Description
Prepares for further file functions and monitoring of the Compact Flash location.

Return value
None.

DetectCFCard

Syntax
#include <file.h>
UCHAR DetectCFCard( void );

Description
This function should be called regularly in order to maintain knowledge of the presence or not of the Compact Flash card.  Upon a new detection of an inserted card this function checks for the presence of the DATA directory and if not present creates it.

Return value
If a Compact Flash card is present a TRUE value is returned, if not card is present a FALSE value is returned.

CreateDataFile

Syntax
#include <file.h>
UCHAR CreateDataFile(UCHAR *data_filename);

Description
Creates a file in the DATA directory called data_filename, this file will be opened and ready to write data to using the write_file function.

Return value
CreateDataFile returns 0 on successfully creating a file in the DATA directory.  If there is an error in creating the file -1 is returned.

write_file

Syntax

#include <file.h>

INT write_file( INT hand, const UCHAR *buf, UINT len );

Description

Following a successful call of CreateDataFile, this function writes a buffer of data to that file.

This function attempts to write len bytes from the buffer pointed to by buf to the file. Except when write is used to write to a text file, the number of bytes written to the file will be no more than the number requested.

Currently the parameter hand is unused and should be set to 0.

Return value

write_file returns the value 0 if the file was written to.

A return value of -1 indicates an error.

InitUart1

Syntax

#include <urt1_drv.h>

void InitUart1(void);

Description

InitUart initialises communications port 1.

Return value

None.

OpenUart1

Syntax

#include <urt1_drv.h>

BOOL OpenUart1(BYTE baud_rate, BYTE config);

Description

OpenUart1 opens communications port 1 with the defined baud_rate and communications protocol, either RS232 or RS485.

The value of baud_rate can be one of the following predefined values as detailed in urt1_drv.h:

 The value of config can be one of the following: 

 Return Value

If the communications port is already open FALSE is returned, if the port is opened by the function call then TRUE is returned.

CloseUart1

Syntax

#include <urt1_drv.h>

void CloseUart1(void); 

Description

CloseUart1 closes communications port 1. 

Return value

None.

QueueUart1TxByte

Syntax

#include <urt1_drv.h>

BOOL QueueUart1TxByte(BYTE tx_byte); 

Description

Sends tx_byte to communications port 1 transmit buffer.  The byte will be added to the transmit buffer and transmitted as soon as possible. 

Return Value

If communications port 1 is closed or the transmit buffer is full FALSE will be returned, otherwise if the byte is successfully added to the transmit buffer then TRUE is returned.

GetUart1RxByte

Syntax

#include <urt1_drv.h>

BOOL GetUart1RxByte(BYTE *rx_byte_ptr); 

Description

If the communications port is open gets the oldest data byte from communications port 1 receive buffer.  

Return Value

If the communications port is open and there is data in the receive buffer then TRUE is returned, otherwise FLASE is returned.

IntToAsc

Syntax

#include <utils.h>

void IntToAsc( UINT num, UCHAR *str );  

Description

Takes a variable of type UINT and converts it into an Ascii string. 

Return Value

None

AscToByte

Syntax

#include <utils.h>

UCHAR AscToByte( const UCHAR *str );  

Description

Takes an Ascii number and returns its byte value. 

Return Value

A value of type UCHAR is returned equivalent to the Ascii number passed.

AscToWord

Syntax

#include <utils.h>

UINT AscToWord( const UCHAR *str );

Description

Takes an Ascii number and returns its value as a UINT.

Return Value

A value of type UINT is returned equivalent to the Ascii number passed.

PutByte

Syntax

#include <utils.h>

void PutByte( UCHAR data );

Description

Sends a byte of data to the second UART transmit buffer.

Return Value

None

OpHexByte

Syntax

#include <utils.h>

void OpHexByte( UCHAR num );

Description

Converts a UCHAR into a Hex Byte and sends the two bytes to the transmit buffer of the second UART.

Return Value

None

OpStr

Syntax

#include <utils.h>

void OpStr( const UCHAR *str );

Description

Sends a string to the second UART transmit buffer.

Return Value

None

OpInt

Syntax

#include <utils.h>

void OpInt( UINT num );

Description

Takes a UINT value, converts it to Ascii and sends this string to the second UART transmit buffer.

Return Value

None

OpTerm

Syntax

#include <utils.h>

void OpTerm( void );

Description

Sends termination characters (CRLF) to the second UART transmit buffer.

Return Value

None

OpStrTerm

Syntax

#include <utils.h>

void OpStrTerm( const UCHAR *str );

Description

As for OpStr but termination characters (CRLF) are also sent to the second UART transmit buffer.

Return Value

None

LogSetup

Syntax
#include <file.h>
void LogSetup( void);

Description
LogSetup function is used to read the parameters from the DEMO_INI.TXT file.

The corresponding global variables written to by the LogSetup function, and used in main.c are as follows:

UCHAR Adc_channels = 0x0F;   // Config, all ADC channels logged
UCHAR Dig_channels = 0x0F;    // Config, all Digital channels logged
UCHAR STX_char = 0x02;        // Serial input STX char
UCHAR ETX_char = 0x03;        // Serial input ETX char
UCHAR Store_rate = 1;             // Config, log every serial sample
UCHAR Log_scheme = 0;          // Config, Set to 1 for serial based logging rate, 0 for timed based
ULONG Log_rate = 20;             // Config, default 1 second logging interval
UINT Baud_rate1 = UART1_BAUD_9600; // Config, default Baud rate 9600
BYTE Comms_protocol = 0;      // Config, Comms protocol default RS232

It is possible to modify the code in main.c to use hard coded values in place of the Setup variables, and reuse the set up variables as alternate parameters. This goes for all the parameters except the following:

Log_scheme
Comms_protocol

All the remaining parameters in DEMO_INI.TXT are simply converted from their ASCII value into the corresponding Hex value. For example a line in DEMO_INI.TXT "Log rate = 100" would result in a the global variable Log_rate being set to a value of 100. So if the code in main.c using Log_rate was hard coded with a fixed value, this variable could be used as an alternate Setup parameter.

The important thing to remember is that in LogSetup() the parameters are read into global variables in the order they appear in DEMO_INI.TXT. That is the parameter names are not looked at only the value after each = sign. You can therefore change the names in the DEMO_INI.TXT file but you can not change the order or add additional parameters. It would be safest to leave the format of this file the same, and simply change the values.

Return value
None

InitAnaIps

Syntax
#include <ana_drv.h>
void InitAnaIps(void); 

Description
Initialises the analogue input lines. 

Return value
None.

StartAdcConv 

Syntax

#include <ana_drv.h>

BOOL StartAdcConv(WORD conv_rate, UCHAR channels); 

Description

Sets up the analogue channels which are to be measured, these are encoded into the parameter channels in a bitwise fashion as detailed below: 

 Several channels may be used, for example to use analogue channel 0 and 1, the parameter channel should be set to 0x3.  If all four channels are to be used, channel should be set to 0x0F.

Return value

The return value is the TRUE if the analogue inputs have already been initialised, and FLASE if not.

StopAdcConv

Syntax
#include <ana_drv.h>
void StopAdcConv(void); 

Description
Stops the analogue input conversions and re-initialises the analogue input lines.

Return value
None.

AnalogueInputConversion

Syntax
#include <ana_drv.h>
void AnalogueInputConversion(void);

Description
A state machine with three states, each call of the function will execute the subsequent state.  The first state sets up the current channel to be converted, switching in turn through each of the required canalogue inputs as set up in StartAdcConv.  The second state sets the conversion process running in the background and the third state reads the converted value and writes it into the appropriate global variable structure (INT AnalogueVals[ 4 ]).

Hence each conversion takes three calls of this function.  This technique is used as the analogue input section requires a setup time following the first state, and an acquisition state following the second state.

The global structure used to store the four analogue input values is an array of four integers.

Values will be between –2047 and +2047 representing the range of –5V to +5V

INT AnalogueVals[ 4 ]; 

Return value
None.

AnalogueInputsToAscii 

Syntax
#include <ana_drv.h>
void AnalogueInputsToAscii(UCHAR channel, UCHAR *str); 

Description
Reads the global variable structure for the channel selected by the parameter channel to obtain the latest value of the selected analogue input and converts it into an Ascii string, pointed to by the parameter str.  This string consists of a signed value between –5.000V and +5.000V. 

Return value
None.

SetDigIoDir; 

Syntax
#include <dig_drv.h>
void SetDigIoDir(BYTE dig_io_no, BYTE io_dir); 

Description
Configures the digital input/output port data direction.  Digital port number is defined by dig_io_no, and the direction is set using io_dir and pre-defined values from dig_drv.h: 

Value	Port direction
DIG_IO_DIR_OP	Output
DIG_IO_DIR_IP	Input

 Return value
None. 

GetDigIpState 

Syntax
#include <dig_drv.h>
BYTE GetDigIpState(BYTE dig_io_no); 

Description
Reads from digital port as selected by dig_io_no.  The digital port must have been previously set as an input using the SetDigIoDir function. 

Return value
The unsigned character returned is the state of the digital port selected.

SetDigOpState 

Syntax
#include <dig_drv.h>
void SetDigOpState(BYTE dig_op_no, BYTE op_state); 

Description
Configures the digital output data.  The selected digital line must have already been configured as an output using the SetDigIoDir function.  Digital port number is defined by dig_io_no, and the state, high or low, is set using op_state and pre-defined values from dig_drv.h: 

Value	Port direction
DIG_IO_STATE_LO	Low
DIG_IO_STATE_HI	High

Return value
None.

ToggleDigOp 

Syntax
#include <dig_drv.h>
void ToggleDigOp(BYTE dig_op_no); 

Description
Toggles the output state of the selected digital line.  The selected digital line must have already been configured as an output using the SetDigIoDir function.  Digital port number is defined by dig_io_no.

Return value
None.

InitRTC 

Syntax
#include <rtc_drv.h>
BOOL InitRTC(void); 

Description
Initialises the real time clock ready for communications. 

Return value
TRUE is returned if the real time clock has successfully been initialised, and FALSE otherwise.

ConstructAsciiDateandTime 

Syntax
#include <rtc_drv.h>
void ConstructAsciiDateandTime(void);

Description
Converts date and time to ASCII, note that ReadDateandTime should be called prior to calling this function in order to obtain the current time.

ConstructAsciiDateandTime converts a time stored as a structure in TimeDateData a series of 2 character (or 4 character in the case of the year) strings.  These strings are global variables:

BYTE AsciiSeconds[2];
BYTE AsciiMinutes[2];
BYTE AsciiHours[2];
BYTE AsciiDate[2];
BYTE AsciiMonth[2];
BYTE AsciiYear[4];

Return value
None.

ReadDateandTime 

Syntax
#include <rtc_drv.h>
void ReadDateandTime(void); 

Description
Obtains the current time from the real time clock and inputs these values into a global variable as detailed below.  The new values will be available in the global variable following completion of this function.

BYTE TimeDateData[7] 

Note that TimeDateData[3] is currently unused. 

Return value
None. 

GetTimeinSeconds 

Syntax
#include <rtc_drv.h>
void GetTimeinSeconds(UCHAR *str);

Description
Reads the current time from the real time clock and converts the number of seconds since the start of the current day.  This value is converted into an ASCII string and written to a supplied location given by str.

Return value
None.

WriteDateandTime 

Syntax
#include <rtc_drv.h>
void WriteDateandTime(const UCHAR *str); 

Description
Sets the time and date of the real time clock using an ASCII string of the following format:
ssmmhhwwddxxyy

Where:
ss = number of seconds
mm = number of minutes
hh = number of hours (24 hour clock)
ww=01
dd = date
xx = month
yy = year 

for example:

12340501210903 passed into this function would set the real time clock to:

 05:34:12  21/09/2003

This function is implemented in the demonstration application command parser.  This means using communications port 2, and the above string preceded by an ‘s’ the current date and time may be set. 

Return value
None.

TestOutputDateandTime

Syntax
#include <rtc_drv.h>
void TestOutputDateandTime(void);

Description
Outputs the current time and date via communications port 2.

Return value
None.

LedOn

Syntax
#include <led_drv.h>
void LedOn(void); 

Description
Switches the LED on. 

Return value
None

LedOff

Syntax
#include <led_drv.h>
void LedOff(void); 

Description
Switches the LED off.

Return value
None

LedToggle 

Syntax
#include <led_drv.h>
void LedToggle(void); 

Description
Toggles the LED. 

Return value
None

GetLedState 

Syntax
#include <led_drv.h>
BOOL GetLedState(void); 

Description
Returns the state of the LED. 

Return value
1 if the LED is on, 0 if off.

NEXT -->

START