;
; BFFCOMMS - PC to PICAXE Serial COMMS API - Ian Hopper (BFF Design Ltd) June 2010
; Ian@builtforfun.co.uk   http://buggies.builtforfun.co.uk/Sim/BFFCOMMS.php
;
; © 2010 BFF Design Ltd
;
; To make the functions avaiable in your AHK scripts include the BFFCOMM_func.ahk file
; by adding the line:
; 
; #Include BFFCOMMS_func.ahk
;
; ...near the top of your script.
;
; See the pre-scripted examples included in the download package for code illustrations.
;
; Rev beta 02 - May 2011, Corrected BFFCOMMS_Purge() arguments in text files
;
;======================================================================================
;
;The BFFCOMMS functions are :-
;
;Open the COM port
;=================
;
;BFFCOMMS_Open(COMPort, Baud, Handle, TimeOut, Abort_Disable)
;   COMPort - Input String, port number - eg COM1, COM2 etc
;   Baud - Input Integer, baud rate - eg 9600, 115200 etc
;   Handle - Output Integer, handle for the opened port
;   Timeout - Optional Input Integer, read timeout period in ms (defaults to zero - no timeout)
;   Abort_Disable - Optional Input Integer, =1 to disable Abort on Error, = 0 to enable (default)
;
;   Return integer, = 0 for success, >= 0 gives windows error code for last error
;
;
;
;Close the COM port
;==================
;
;BFFCOMMS_Close(Handle)
;   Handle - Input Integer, handle for the opened port (from BFFCOMMS_Open() function call)
;
;   Return integer, = 0 for success, >= 0 gives windows error code for last error
;
;
;
;Purge the COM port read buffer
;==============================
;
;BFFCOMMS_Purge(Handle)
;   Handle - Input Integer, handle for the opened port
;
;   Return integer, = 0 for success, >= 0 gives windows error code for last error
;
;
;
;Send byte string up to 16 bytes long to the COM port
;====================================================
;
;BFFCOMMS_Send(Handle, dFormat, b1, b2, b3........ b16)
;   Handle - Input Integer, handle for the opened port
;   dFormat - Input String, of form AABBBB etc, length gives number of bytes, character value gives type - A=ascii, B=data, C=carriage return, L=line feed
;   b1 - Output byte, data byte value 0-255 or single character ascii character
;   b2 to b16 - Optional output bytes
;
;   Return integer, = 0 for success, =-1 zero length format definition, >= 0 gives windows error code for last error
;
;
;
;Get byte string up to 16 bytes long from the COM port
;=====================================================
;
;BFFCOMMS_Get(Handle, dFormat, b1, b2, b3........ b16)
;   Handle - Input Integer, handle for the opened port
;   dFormat - Input String, of form AABBBB etc, length gives number of bytes, character value gives type - Q=ascii qualifier, A=ascii, B=data, C=carriage return, L=line feed
;     Q qualifiers when present should be the first characters in dFormat, 
;   b1 - Output byte, data byte value 0-255 or single character ascii character
;   b2 to b16 - Optional output bytes
;
;   Return integer, = 0 for success, = -1 timeout has occured, = -2 zero format string length, >= 0 gives windows error code for last error
;
;NOTE if ascii quailifiers are found in the serial data stream they will be echoed in the relevant returned bytes.
;The timeout behaviour of the function when it is listening for qualifier bytes is determined by the global variable
;BFFCOMMS_QTO. If BFFCOMMS_QTO = 0 then the function will wait indefinately for the qualifier bytes to appear in the
;data stream. If BFFCOMMS_QTO = 1 then the function will timeout if no data is recieved within the timeout period set in
;function BFFCOMMS_Open() whilst it waits for qualifier bytes.
;
;If a timeout is specified in BFFCOMMS_Open() then it will always be active when the function is listening for non-qualifier
;bytes.
;
;IMPORTANT - if your serial cable is present but not connected to a PICAXE download circuit then the line voltages might float
;and the BFFCOMMS_Get() function may return "ghost" byte values under some circumstances.
;