Xline X10i

A call to ConfigurePulsedInput() must be made first.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

Function Prototype BeginPulsedInputCheck:int( usbInputBitId inputBitID )

recommended if real time performance is important in your code. The functionality is slightly different in that the previous instead of the current security switch status is returned. If a switch change occurs, then two calls to CachedReadAndResetSecuritySwitchFlags( ) would be required before the change is visible.

The majority of X-line API calls work at relatively high speeds, limited mainly by USB transfer constraints (4ms per message). Security Pipe functions work at slow speeds because the onboard PIC performs the processing for these operations via a slow I2C bus.

When the function ReadAndResetSecuritySwitchFlags( ) is called, the following events occur:

• A USB packet is sent to the X-line board requesting the security switch flags.
• The board asks the PIC chip for the current security switches (this is where most time is taken).
• The board returns the PIC response to the PC via the USB channel.

CachedReadAndResetSecuritySwitchFlags( ) changes the above sequence as follows:

• A USB packet is sent to the X-line board requesting the security switch flags.
• The board returns the previously obtained security switch flags to the PC via the USB channel.
• The board communicates with the PIC chip requesting the current security switch states.

Stages 2 and 3 are reversed and the previous security switches are immediately returned to the PC. If the function is called again before stage 3 is complete then the response will be delayed until stage 3 is complete from the previous call. It is therefore recommended that a minimum of a one second gap should occur between calls to CachedReadAndResetSecuritySwitchFlags( ).

Function Prototype
Method CachedReadAndResetSecuritySwitchFlags:Int( closedSwitches:Byte Ptr, openSwitches:Byte Ptr )

Programming Considerations
Either ReadAndResetSecuritySwitchFlags( ) or CachedReadAndResetSecuritySwitchFlags( ) should be used in your code. They should not be used interchangeably.

It can differentiate between the following devices: 24LC01, 24LC02, 24LC04, 24LC08, 24LC16, 24LC32, 24LC64, 24LC128, 24LC256 and 24LC512.

The function requires a single parameter, , which is a pointer to a structure of type X10EEPROM. This function will populate the structure as reproduced below:

Type x10EEPROM
    Field pageSize:Byte			' e.g. For 24LC04 value = 16
    Field numAddressBytes:Byte		' e.g. For 24LC04 value = 1
    Field maxAddress:Short			' e.g. For 24LC04 value = 511
    Field i2cAddress:Byte			' e.g. For 24LC04 value = 0x50
EndType

The variable specifies the EEPROM page size in bytes.

The variable specifies the number of address bytes on the EEPROM. This can either be 1 or 2.

The variable specifies the maximum available EEPROM address.

The variable specifies the EEPROM i2c address.

Calls to CheckEEPROM() and ConfigureEEPROM() are automatically made during X-line board initialisation in an attempt to detect and configure the currently fitted EEPROM.

Function Prototype
Method CheckEEPROM:Int( eepromConfig:X10EEPROM )

For a more detailed description of ccTalk Mode 1, please refer to ccTalk explanation describe further in this manual..

It is possible to set up to 8 ccTalk devices on an X-line board: 4 on Port A and 4 on Port B. Once a Port has been set up for ccTalk Mode 1 operation, only the following serial API functions are available for that port:

• ConfigureCCTalkPort()
• EmptyPolledBuffer()
• ReceivePolledMessage()
• DeletePolledMessage()

It is possible to call SetConfig() to re-configure the port to RS232/RS232 Polled/ccTalk Mode 0 operation if required.

Two parameters are required for this function:

The parameter determines whether the configuration data is for Port A or Port B.

The parameter is a pointer to a type CCTalkConfig containing ccTalk Mode 1 configuration data. This is what the structure looks like:

Type CCTalkConfig
    Field device_number:Byte
    Field PollMethod:Byte Ptr
    Field next_trigger_device:Byte
    Field poll_retry_count:Byte
    Field polling_interval:Int
    Field max_response_time:Short
    Field min_buffer_space:Byte
    Field poll_msg[MAX_POLL_MSG_LENGTH]
    Field inhibit_msg[MAX_POLL_MSG_LENGTH]
EndType

The variable specifies the device number for the device on the current port. This can take the values 0 – 3 thus enabling 4 devices.

The variable specifies how the device is polled. It can take four values: Repeated, Triggered, Once and Disabled. The poll method must be set to Repeated for automatic polling. The Disabled option shows that this device is not present. The Once option is a special case, used to send a single message to a specific device. The Triggered method is used if this device is triggered immediately after a device configured to Once or Repeated method. A Triggered device will not send out messages by itself, only if it is set to poll immediately after another device – see next paragraph.

The variable specifies the next device to trigger immediately after this device has polled. It can take the value 0 – 3. The device that will be triggered after this device must have its set to Triggered. If no device is to be triggered after this device is polled then set this variable to NO_TRIGGER.

The parameter specifies the maximum number of retries, once a response timeout has occurred, before sending an inhibit message. This can range from 0 to 255.

The variable is the time, in ms, between polls when the variable is set to Repeated. It is also the time until the single message is sent when is set to Once. This variable can be in the range of 10 – 2550ms, but it will be rounded down to the nearest 10ms multiple.

The variable specifies the maximum time, in ms, to wait for a response from the device. It can be in the range of 0 – 65535ms. If no response is obtained within this time period then an Inhibit message is sent to the device and the internal X-line board variable is set to Disabled.

The variable specifies the minimum amount of receive buffer space allowed, below which an inhibit message will automatically be sent and polling stopped. The buffer is stored in batterybacked “xdata” memory space on the X-line board and will be available after power loss. At this time the buffer space available for each ccTalk Device is 600 bytes.

The variable is the polling message and can be up to 25 bytes long. Note: The message length is defined in the actual message. The message byte is in position 1 for ccTalk. This value does not include the 5 header and checksum bytes.

The variable is the inhibit message and can be up to 25 bytes long. Note: The message length is defined in the actual message. The message byte is in position 1 for ccTalk. This value does not include the 5 header and checksum bytes.

Once these parameters have been defined, automatic polling will commence if is set to Repeated. All received data (excluding local echo) will be stored in a buffer for the device. The buffer is 600 bytes long. The buffer may be read using ReceivePolledMessage() and will include a status byte indicating whether the device has been inhibited.

Polling stops automatically once the space left in the buffer falls below a certain level. It also stops if a response timeout occurs and the maximum number of retries has been reached, as defined in . In either of these situations an inhibit message will be sent. If the device has been inhibited polling can be restarted as follows:

• Sending a single message re-enabling the ccTalk device.
• Re-starting polling with another call to ConfigureCCTalkPort().

Note: (1) is needed because an inhibit message will have been sent to the device.

If a device is configured for polling and that device triggers another device, and from that possibly more devices, there are some points to be aware of. If one of the devices becomes inhibited, or if it is reconfigured with the Disabled option, then that device and all devices triggered after it will cease polling. If it is reconfigured to the Once option, it will poll once and all other devices triggered after it once.

Function Prototype
ConfigureCCTalkPort:Int( port:Int, cctalk_config:CCTalkConfig )

Programming Considerations
The function SetConfig() must be called first to ensure that the serial port is correctly configured and set to PORT_CCTALK_MODE1 operation.

This function is only available in ccTalk Mode 1.

The function requires a single parameter, , which is a pointer to a structure of type X10EEPROM. Please see the description for CheckEEPROM() for the definition of the structure X10EEPROM. Calls to CheckEEPROM() and ConfigureEEPROM() are automatically made during X-line board initialisation in an attempt to detect and configure the currently fitted EEPROM.

Function Prototype
ConfigureEEPROM:Int( eepromConfig:X10EEPROM )

This function is used to configure reading of input pulses on parallel devices, for example coin acceptors. The following functions are used in conjunction with this function:

BeginPulsedInputCheck()
EndPulsedInputCheck()
ResetPulsedInputCounter()
DecrementPulsedInputCounter()
ReadPulsedInputCounter().

Pulse reading will not begin until a call to BeginPulsedInputCheck() is made.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

The parameter specifies the minimum pulse length, in ms, for valid input pulses.

The parameter specifies whether the input is active high or low, and can only take the values High or Low.

Function Prototype ConfigurePulsedInputEx:int( usbInputBitId inputBitID, BYTE pulseLowerTime, ActiveState inputActiveState )

Programming Considerations

This function is only supported on the X10i and X15 boards. It is not supported on the X10 board.

This function must be called if stepper motors are to be controlled by the X-line board. The parameters determine the number of reels fitted (up to 3, identified as reel 0, reel 1 and reel 2), the number of positions per turn and the number of steps per symbol. (Note: One step is two positions when full stepping, but only one position when half stepping).

At power up, the USB board will initialise with no reels fitted until this function has been called. The function may be called with the number of reels set to 0 to disable the reel function and return associated outputs to their normal operation.

If, for example, only one reel is configured, then the outputs that would be associated with the two unused reel positions will behave as normal outputs. The system is, therefore, quite flexible.

Note: There is no flexibility in allocation of particular outputs to particular reels: if one reel is configured, it will use outputs OP16/17/18/19 and input IP6. The second reel, if configured, will use outputs OP20/21/22/23 and input IP7. The third reel, if configured, will use outputs OP24/25/26/27 and input IP8.

Function calls such as SetOutputs(), will not corrupt outputs configured for use by reels if they try to access them.

Function calls such as GetInputs(), will read and return inputs correctly, whether configured for use with reels or not.

The variable is the number of half-steps required to turn the reel through one turn. It is used by the synchronisation error checking software.

The variable is not currently used and is reserved for future enhancements.

Function Prototype
ConfigureReels:Int( numberOfReels:Byte, halfStepsPerTurn:Byte, stepsPerSymbol:Byte )

Programming Considerations
This function must be called before stepper motor outputs can be used.

• The RS232 hardware is used instead of ccTalk.
• It is possible to define whether or not local echo suppression is implemented.
• This is a more generic driver in that the message length byte is not set and can be defined, along with an offset byte to obtain the proper message length.

Apart from these differences, operation is identical to ccTalk Mode 1. Please read the section ConfigureCCTalkPort() for more details.

It is possible to set up to 8 polled RS232 devices on an X-line board: 4 on Port A and 4 on Port B. Once a Port has been set up for RS232 Polled operation, only the following serial API functions are available for that port:

• ConfigureRS232Poll()
• EmptyPolledBuffer()
• ReceivePolledMessage()
• DeletePolledMessage()

It is possible to call SetConfig() to re-configure the port to RS232/ccTalk Mode 0/ccTalk Mode 1 operation if required.

Two parameters are required for this function:

The parameter determines whether the configuration data is for Port A or Port B.

The parameter is a pointer to a structure of type RS232PollConfig containing RS232 Polled configuration data. This is what the structure looks like:

Type RS232PollConfig
    Byte device_number:Byte
    pmethod:PollMethod
    next_trigger_device:Byte
    poll_retry_count:Byte
    polling_interval:Int
    remove_local_echo:Int
    length_byte_offset:Byte
    add_to_length_byte:Byte
    max_response_time:Short
    min_buffer_space:Byte
    poll_msg:Byte[MAX_POLL_MSG_LENGTH]
    inhibit_msg:Byte[MAX_POLL_MSG_LENGTH]
EndType

'	typedef struct
'	{
'	BYTE device_number;
'	PollMethod method;
'	BYTE next_trigger_device;
'	BYTE poll_retry_count;
'	int polling_interval;
'	BOOL remove_local_echo;
'	BYTE length_byte_offset;
'	BYTE add_to_length_byte;
'	WORD max_response_time;
'	BYTE min_buffer_space;
'	BYTE poll_msg[MAX_POLL_MSG_LENGTH];
'	BYTE inhibit_msg[MAX_POLL_MSG_LENGTH];
RS232PollConfig;

The variables , , , , , , , and are identical to those used in ccTalk Mode 1 operation. Please read the section ConfigureCCTalkPort() for more details.

The variable specifies whether or not local echo is removed. This option should only be used in situations where local echo will arise. Otherwise, loss of valid received data may occur.

The variable specifies where in the message packet the length byte is located. For example if located in the first byte then this would be 0. Only single length bytes are allowed.

The variable specifies a value to add onto the value stored in the length byte to obtain the proper message length. This is used in protocols where the message contains header and checksum bytes that are ignored in the message length byte.

Function Prototype
Method ConfigureRS232Poll:Int( port:Int, pollConfig:RS232PollConfig )

Programming Considerations The function SetConfig() must be called first to ensure that the serial port is correctly configured and set to PORT_RS232_POLLED operation.

This function is only available in RS232 Polled Mode.

If the counter is currently zero then no decrement will occur. A call to ConfigurePulsedInput() must be made first.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

Function Prototype DecrementPulsedInputCounter:int( usbInputBitId inputBitID )

Two parameters are required for this function:

The parameter determines whether Port A or Port B is used.

The parameter specifies the device number and can take a value 0 – 3.

Function Prototype
Method DeletePolledMessage:Int( port:Int, deviceNumber:Byte )

Programming Considerations
The function SetConfig() must be called first to ensure that the serial port is correctly configured and set to either PORT_RS232_POLLED or PORT_CCTALK_MODE1 operation. Also a call to ConfigureCCTalkPort() or ConfigureRS232Poll() must be made to configure this device.

This function is only available in RS232 Polled Mode or ccTalk Mode 1.

This releases the X-line SPI outputs OP0 and OP1 for use by other functions.

Function Prototype
DisableSPI:int( void )

Two parameters are required for this function:

The parameter determines whether Port A or Port B is used.

The parameter specifies the device number and can take a value 0 – 3.

Function Prototype
EmptyPolledBuffer:Int( port:Int, deviceNumber:Byte )

Programming Considerations
The function SetConfig() must be called first to ensure that the serial port is correctly configured and set to either PORT_RS232_POLLED or PORT_CCTALK_MODE1 operation. Also a call to ConfigureCCTalkPort() or ConfigureRS232Poll() must be made to configure this device.

This function is only available in RS232 Polled Mode or ccTalk Mode 1.

A call must be made to this function before using any SPI commands.

The SPI protocol uses two X-line outputs for device communications: OP0 for the clock and OP1 for data output. Once the SPI protocol is enabled then these outputs can only be used for SPI commands. A call to DisableSPI() must be made to free up these outputs. The X-line input IP18 is also used as a data input from the SPI device.

Function Prototype
EnableSPI:int( void )

This function reports the version number of the 8051 software. This is downloaded to the X-line device during enumeration.

Function Prototype Get8051Version:String()

Programming Considerations This returns a string of no more than 10 characters including the null terminator.

The Memory pipe is used for this function.

The X10i/X15 boards can work at two different speeds: If the board is plugged into a USB 1.1 hub Then it will work at “full speed”, and if it is plugged into a USB 2 hub then it will work at “high speed”. High speed is considerably faster than full speed and this allows many X10i functions to perform faster.

The X10 board can only work in “full speed” mode. Plugging it into a USB 1.1 or a USB 2 hub makes no difference.

This function returns the speed at which the currently fitted board is working at.

Function Prototype
BOOL GetBoardSpeed( LPBYTE boardSpeed );

Programming Considerations
The boardSpeed parameter is a pointer to a BYTE which reports the speed at which the currently fitted board is working at.

Three possible values can be returned:

• UNKNOWN_SPEED : The speed is unknown so therefore the board is not behaving correctly.
• USB_1_1_FULL_SPEED : The board is working at full speed.
• USB_2_0_HIGH_SPEED : The board is working at high speed. The X10 cannot return this value.

This function reports the serial number of the Dallas chip on the X-line board. Every board has a unique serial number. The first byte returned is the family code of 0x01. The next 6 bytes are a unique serial number and the final 8th byte is a CRC byte. Although the CRC byte is made available to the user, the data has already been tested for integrity using the CRC and the result is returned in crcValid.

GetDallasSerialNumber() is a slow Security Pipe function.

Function Prototype GetDallasSerialNumber:String()

Programming Considerations This returns a string of 8 bytes in serialNumberDallas. It sets crcValid = TRUE if the data passes the 8-bit CRC test.

This function is only supported on the X10i and X15 boards. It is not supported on the X10 board.

This function reports the version of the Windows DLL that is providing access to the USB device. It may be used to check that the correct DLL has been installed and is being called. It does not require a device handle and can be called without a USB device connected.

Programming Considerations This returns a string of no more than 10 characters including the null terminator.

No pipes are used for this function.

This function is ascertains which board is currently fitted.

Function Prototype
GetFittedBoard:int( fittedBoard:byte ptr )

Programming Considerations
The fittedBoard parameter is a pointer to a BYTE which will contain information about the currently fitted board.

Four values can be returned:

• UNIDENTIFIED_BOARD : The currently fitted board is unknown
• X10_BOARD : An X10 is fitted
• X10I_BOARD : An X10i is fitted
• X15_BOARD : An X15 is fitted

This function returns the error code for the last function call that failed and updated the error code.

Function Prototype usbErrorCode GetLastError()

Return value A variable of type usbErrorCode that describes the reason for failure, also see chapter on API Return Codes.

Programming Considerations Not all failing function calls have an error code associated with them, in which case the error code returned, if requested, will relate to a previous function call that failed.

The use of multiplexed input lines is outlined in the following diagram. Note that blocking diodes must be fitted to each switch-line used to prevent channels from interfering with one another.

Official site

The function GetMultiplexedInputs returns the state of the multiplexed inputs. The data is returned as the following type definition

Type usbMultiplexedInput
    Field byMuxStatus:Byte
    Field byMuxInp:Byte[4,3]
EndType

The structure member byMuxStatus indicated the status of the input multiplexer. A non-zero value means that the input multiplexer in enabled, a zero value means that the input multiplexer is disabled.

The structure member byMuxInp contains the status of each input pin for each channel. There are four channels each containing all 24 inputs IP0-IP23 (24 bits = 3 bytes).

There are 4 channels and each channel is controlled by one of output pins 12, 13, 14 or 15 as shown in the diagram. For the first 1mS time slice, output 12 is toggled low while outputs 13, 14, and 15 are set high. Input lines IP0-IP23 are read and stored as channel 0. Next output 12 is toggled high and output 13 is toggled low and the 24 input bits stored as channel 1. This procedure is repeated until all input channel have been read, as summarised in the table below. Effectively each individual multiplexed input channel is read once every 4mS.

Function Prototype GetMultiplexedInputs:int( inputs:usbMultiplexedInput )

This function reads the parallel hopper coin release status after a call to ReleaseParallelHopperCoins() has been made.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

The parameter is a pointer to a structure of type ReleaseHopperCoinsStatus. This is continuously updated during coin release. It will be set to one of five values:

• Running - Coins are still being released and there are no problems.
• Failure - The timeout has occurred without a coin being released.
• Success - All required coins have been successfully released.
• InitJam (only available on the X10i and X15) – An attempt has been made to release additional
coins while an existing coin release was in progress.
• Jam (only available on the X10i and X15) - The time taken to release a coin exceeded the
maximum pulse length.

The parameter is a pointer to a BYTE which will contain the number of coins that have currently been released.

Function Prototype
GetParallelHopperStatus:int( usbInputBitId inputBit, ReleaseHopperCoinsStatus *status, BYTE *coinsReleased )

This value is reset after it is returned.

The ‘parityErrors’ parameter is a pointer to a WORD where the parity error count will be returned.

Function Prototype
GetParityErrors:Int( port:Int, parityErrors:Short Ptr )

Programming Considerations
The function SetConfig() must be called first to ensure that the serial port is correctly configured.

This function reports the serial number of the PIC (which is blank when supplied by Heber). If the serial number is not set by the user (using SetPICSerialNumber) then this function will return a random 8 character string.

The security of the PIC is controlled by unlockio.lib and this serial number is not related to the security.

Function Prototype GetPICSerialNumber:String()

Programming Considerations This returns a string of no more than 9 characters including the null terminator.

This function reports the version of X-line PIC (security device) firmware.

Function Prototype GetPICVersion:string()

Programming Considerations This returns a string of no more than 10 characters including the null terminator.

This function reports the X-line Development Suite Product version.

Function Prototype BOOL GetProductVersion:String()

Programming Considerations This returns a string of no more than 10 characters including the null terminator.

No pipes are used for this function.

An input becomes jammed if the pulse has exceeded it’s upper limit (as defined in ConfigurePulsedInputEx()). Once an input is jammed then further pulses (whether valid or not) will not be recorded.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

The pointer parameter reports TRUE if the input is jammed and FALSE otherwise.

The pointer parameter reports the number of coins that have currently been released.

Function Prototype GetPulsedInputStatus:int( usbInputBitId inputBit, BOOL *jamStatus, BYTE *inputCounterValue )

This function returns the reel status for all reels, even only some of the reel outputs are configured as reels. The data returned in the structure describes, for each reel, the following:

• The current reel position (0-255)
• The last reel position error value (-128 to +127), which is the difference between actual position and expected position when the opto-detector was last passed.
• The reel busy state, which will be TRUE if busy and the last spin request has not yet been completed
• The synchronisation state. When FALSE, the reel position counter will be set to 0 as the opto-detector is passed, and the synchronisation state will be set to TRUE. When TRUE, the position counter will be copied into the error counter as the opto-detector is passed and the synchronisation state will remain set to TRUE. It can only be set to FALSE again by ReelSynchroniseEnable().

Function Prototype
GetReelStatus:Int( status:Byte Ptr )

Programming Considerations
Use this function regularly to check that reels remain synchronised.

This function is now obsolete because the reel position and error are stored as BYTE’s. Please use GetReelStatusEx() instead, because the reel position and error are stored as WORD’s – this accommodates 200 step reels.

Note: On a reels initial spin the position field data is invalid until the X-line board has detected the presence of the opto flag and the synchronised field has been set.

This function returns the reel status for all reels, even if not all reels are configured active. The data returned in the structure describes, for each reel, the following:

• The current reel position (0-65535)
• The last reel position error value (-32768 to +32767), which is the difference between actual position and expected position when the opto-detector was last passed
• The reel busy state, which will be TRUE if busy and the last spin request has not yet been completed
• The synchronisation state. When FALSE, the reel position counter will be set to 0 as the opto-detector is passed, and the synchronisation state will be set to TRUE. When TRUE, the position counter will be copied into the error counter as the opto-detector is passed and the synchronisation state will remain set to TRUE. It can only be set to FALSE again by ReelSynchroniseEnable().

Note: On a reels initial spin the position field data is invalid until the X10i has detected the presence of the opto flag and the synchronised field has been set.

This function is now recommended instead of GetReelStatus() because the reel position and error are now stored as WORD’s instead of BYTE’s. This accommodates 200 step reels.

Function Prototype
GetReelStatusEx:Int( )

Programming Considerations
Use this function regularly to check that reels remain synchronised.

This function is used to either enable or disable input multiplexing. Once enabled then outputs OP12, OP13, OP14 and OP15 are used exclusively to strobe the input multiplexer. Each output is sequentially pulsed low for 1mS and the inputs are read and stored at the end of the pulse.

The parameter is used to specify whether input multiplexing should be enabled. It can equal either InputMultiplexDisabled or InputMultiplexEnabled.

Function Prototype InputMultiplexing:int( usbInputMultiplexing:int )

Four security switch inputs are continuously monitored. Each time they change state, the new state is stored in a circular buffer with a time stamp from the real time clock. The time stamp format is the same as the real time clock format. The switch locations are:

• Switch 0 = Bit 0
• Switch 1 = Bit 1
• Switch 2 = Bit 2
• Switch 3 = Bit 3

The buffer can store up to ten readings. Each call to this function returns the next oldest result. The buffer is circular, so the results will repeat after 10 function calls.

Reading of switches and storing of results occurs, whether the USB board is powered or not.

Function Prototype
NextSecuritySwitchRead:Int( time:Int Ptr, switches:Byte Ptr )

The

Function Prototype
ReadLargeSRAM:Int( address:Int, data:Byte Ptr, totalLength:Short )

Programming Considerations
This is the same as ReadSRAM(), however it is possible to address up to 0x70000 on the X10i instead of 0x7e00 and up to 0xF0000 on the X15. This means that the function can address up to 448k of SRAM on the X10i and 960k on the X15 instead of 32k (as on the X10).

This function is only supported on the X10i and X15 boards. It is not supported on the X10 board.

A call to ConfigurePulsedInput() must be made first.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

The parameter is a pointer to a BYTE where the returned counter value will be stored.

Function Prototype ReadPulsedInputCounter:int( usbInputBitId inputBitID, BYTE *inputCounterValue)

The

The length parameter indicates how many bytes were received.

Function Prototype
Receive:Int( port:Int, data:Byte Ptr, length:Int Ptr )

Programming Considerations
The X-line board stores received serial data in a 600-byte circular buffer. If more than 600 bytes have been received since the last call to Receive() then the oldest data will be lost.

The function SetConfig() must be called first to ensure that the serial port is correctly configured.

This function is not available in RS232 Polled Mode or ccTalk Mode 1.

SetConfig() must have set Parity to DATA_BIT_9PARITY for this function to work correctly.

Function Prototype
Method Receive9BitData:Int( port:Int, data:Short Ptr, length:Int Ptr )

Programming Considerations See Receive() above.

The buffer is a FIFO (first in, first out) and is 600 bytes long. The message remains in the buffer until a call to DeletePolledMessage() is made. This is required to preserve the message in case power loss occurs.

The parameters for this function are described as follows:

The parameter determines whether Port A or Port B is used.

The parameter specifies the device number and can take a value 0 – 3.

The parameter is a pointer to a buffer where the received message will be stored.

The parameter is a pointer to an unsigned int that will return the number of bytes in the received message.

The parameter is a pointer to a BOOL that specifies whether the device has been inhibited.

Function Prototype
ReceivePolledMessage:Int( port:Int, deviceNumber:Byte, data:Byte Ptr, length:Int Ptr, inhibited:Int Ptr )

Programming Considerations
The function SetConfig() must be called first to ensure that the serial port is correctly configured and set to either PORT_RS232_POLLED or PORT_CCTALK_MODE1 operation. Also a call to ConfigureCCTalkPort() or ConfigureRS232Poll() must be made to configure this device.

This function is only available in RS232 Polled Mode or ccTalk Mode 1.

A synchronisation flag (state) is used to control initialisation of the reel position counter.

After power-up or a call to ReelSynchroniseEnable(), the synchronisation state will be FALSE. The reels must be configured using ConfigureReels (), then ramp tables must be defined for each reel using SpinRampUp() and SpinRampDown() functions. Finally, each reel is spun through at least one turn using SpinReels(). A call to GetReelStatus() should show that each reel is now synchronised with zero error count.

Synchronisation state: When FALSE, the reel position counter will be set to 0 as the opto-detector is passed, and the synchronisation state will be set to TRUE. When TRUE, the position counter will be copied into the error counter as the opto-detector is passed and the synchronisation state will remain set to TRUE. It can only be set to FALSE again by ReelSynchroniseEnable().

Function Prototype
ReelSynchroniseEnable:Int( reelNumber:Byte )

Programming Considerations
The reels must be spun through at least one full turn after calling this function, to ensure that the optodetector is passed.

Note: Reels will only synchronise when the reel spins past the position-0 opto-detector while spinning forwards (positive direction/step size value).

This is a non-blocking function, so in order to read the release status a call to GetParallelHopperStatus() must be made.

This function works by setting a specified output high – this will turn the coin hopper motor on and start to release coins. Simultaneously an input is read counting off pulses – these pulses equate to released coins. If all the required coins are not released, and a specified timeout occurs, it will be assumed that an error has occurred. In this event the output will be set low (turning off the hopper motor) and an error will be returned – see function GetParallelHopperStatus().

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used. These pulses equate to released coins.

The parameter specifies the minimum pulse length, in ms, for valid input pulses.

The parameter specifies the input is active state. This can be one of the following four values (two on an X10):

• Low – the input is active low. Complete low pulses (with a minimum length specified in pulseLowerTime) are identified as released coins. Immediately following the final coin pulse, the motor is turned off.
• High – the input is active high. Complete high pulses (with a minimum length specified in pulseLowerTime) are identified as released coins. Immediately following the final coin pulse, the motor is turned off.
• FallingEdge – the input is active low. Low pulses (with a minimum length specified in pulseLowerTime) are identified as released coins. pulseLowerLength into the final coin pulse, the motor is turned off. This is useful for very sensitive hoppers because the board does not wait for the complete final pulse before turning the motor off.
• RisingEdge – the input is active high. High pulses (with a minimum length specified in pulseLowerTime) are identified as released coins. pulseLowerLength into the final coin pulse, the motor is turned off. This is useful for very sensitive hoppers because the board does not wait for the complete final pulse before turning the motor off.

Note: If the input is already active and a call to ReleaseParallelHopperCoins() is made, an error will not be returned, but the ReleaseHopperCoinsStatus shall be set to return the status InitJam when calling function GetParallelHopperStatus() (only on an X10i or X15).

The parameter specifies the output. This will be set high until all required coins are released, or until timeout in which case it is assumed there is a failure.

The parameter specifies a timeout, in ms, for coin release. If this timeout occurs with no coin being released, it is assumed a fault has occurred and the output will be set low.

The parameter specifies the number of coins to release.

Even after the required number of coins have been released, the board will continue to count coins on the designated input. Call EndPulsedInputCheck() to stop the counter.

Function Prototype ReleaseParallelHopperCoins( usbInputBitId inputBit, BYTE pulseLowerTime, ActiveState inputActiveState UsbOutputBitId outputBit, WORD coinTimeout, BYTE coinsToRelease )

Programming Considerations This function has been deprecated. You should use ReleaseParallelHopperCoinsEx() instead.

This is a non-blocking function, so in order to read the release status a call to GetParallelHopperStatus() must be made.

This function works by setting a specified output high – this will turn the coin hopper motor on and start to release coins. Simultaneously an input is read counting off pulses – these pulses equate to released coins. If all the required coins are not released, and a specified timeout occurs, it will be assumed that an error has occurred. In this event the output will be set low (turning off the hopper motor) and an error will be returned – see function GetParallelHopperStatus().

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used. These pulses equate to released coins.

The parameter specifies the minimum pulse length, in ms, for valid input pulses.

The parameter specifies the maximum pulse length, in ms, for valid input pulses. A value of zero implies an infinite maximum pulse length (equivalent to calling ReleaseParallelHopperCoins() function).

Note: If the maximum pulse width is exceeded then the motor will be turned off and the status (when calling GetParallelHopperStatus()) will be set to Jam.

The parameter specifies the input is active state. This can be one of the following four values:

• Low – the input is active low. Complete low pulses (with a minimum length specified in pulseLowerTime and maximum length specified in pulseUpperTime) are identified as released coins. Immediately following the final coin pulse, the motor is turned off.
• High – the input is active high. Complete high pulses (with a minimum length specified in pulseLowerTime and maximum length specified in pulseUpperTime) are identified as released coins. Immediately following the final coin pulse, the motor is turned off.
• FallingEdge – the input is active low. Low pulses (with a minimum length specified in pulseLowerTime and maximum length specified in pulseUpperTime) are identified as released coins. pulseLowerLength into the final coin pulse, the motor is turned off. This is useful for very sensitive hoppers because the board does not wait for the complete final pulse before turning the motor off.
• RisingEdge – the input is active high. High pulses (with a minimum length specified in pulseLowerTime and maximum length specified in pulseUpperTime) are identified as released coins. pulseLowerLength into the final coin pulse, the motor is turned off. This is useful for very sensitive hoppers because the board does not wait for the complete final pulse before turning the motor off.

Note: If the input is already active and a call to ReleaseParallelHopperCoinsEx() is made, the status (when calling GetParallelHopperStatus()) will be set to InitJam.

The parameter specifies the output. This will be set high until all required coins are released, or until timeout in which case it is assumed there is a failure.

The parameter specifies a timeout, in ms, for coin release. If this timeout occurs with no coin being released, it is assumed a fault has occurred and the output will be set low.

The parameter specifies the number of coins to release.

Even after the required number of coins have been released, the X-line board will continue to count coins on the designated input. Call EndPulsedInputCheck() to stop the counter.

Function Prototype ReleaseParallelHopperCoinsEx:int( usbInputBitId inputBit, BYTE pulseLowerTime, BYTE pulseUpperTime, ActiveState inputActiveState UsbOutputBitId outputBit, WORD coinTimeout, BYTE coinsToRelease )

Programming Considerations

This function replaces the deprecated function ReleaseParallelHopperCoins().

A call to ConfigurePulsedInput() must be made first.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

Function Prototype ResetPulsedInputCounter:int( usbInputBitId inputBitID )

The function is blocking” and will not return control until the transmission has completed or has failed. Therefore the delay at low baud rates could be lengthy.

The length parameter indicates how many bytes must be transmitted.

A buffered (“non-blocking”) version of this function that allows transmission of data as a background task may be developed in future.

Function Prototype
Send:Int( port:Int, data:Byte Ptr, length:Int )

Programming Considerations
the function SetConfig() must be called first to ensure that the serial port is correctly configured.

this function is not available in RS232 Polled Mode or ccTalk Mode 1.

SetConfig() must have set Parity to DATA_BIT_9PARITY for this function to work correctly.

Function Prototype
Send9BitData:Int( port:Int, data:Short Ptr, length:Int )

Programming Considerations
See Send() above.

This function handles all message formatting and checksum creation automatically.

The parameter is a code that defines the type of message to send.

The parameter is the index number of the message being sent. This number is generated by the host machine and starts at 00h. It is incremented every time a new message is sent, up to a value of FFh after which it rolls over to 00h. This ID is used to determine which lost messages may require re-sending by the host.

The parameter defines the number of message bytes to send to the SEC device. This number should not include the command, id or checksum. It should only define the number of data bytes to send.

The parameter is an array of bytes containing the message to send.

The parameter defines the time, in ms, after the message has been send that a response from the device should be expected.

The parameter defines the number of bytes expected back from the SEC device. This number must only equal the number of data bytes expected back from the device, not the command, id and checksum confirmation bytes.

The parameter is an array of bytes where the received message will be stored. This will contain the complete received message including checksum etc.

Function Prototype
SendSEC:Int( command:Byte, id:Byte, numberOfTxBytes:Byte, txMessage:Byte Ptr, waitTimeMs:Byte, numberOfRxBytes:Byte, rxMessage:Byte Ptr )

Programming Considerations
The SPI protocol must be enabled, using EnableSPI(), before calling this function.

There is a size limit of 16 bytes for both transmit and receive messages.

Only SPI mode 2 is supported.

The parameter defines the number of message bits to send.

The parameter is an array of bytes containing the message to send.

The parameter defines the time, in ms, after the message has been send that a response from the device should be expected.

The parameter defines the number of bits expected back from the SPI device.

The parameter is an array of bytes where the received message will be stored.

Function Prototype
SendSPI:Int( numberOfTxBits:Byte, txMessage:Byte Ptr, waitTimeMs:Byte, numberOfRxBits:Byte, rxMessage:Byte Ptr )

Programming Considerations
The SPI protocol must be enabled, using EnableSPI(), before calling this function.

There is a size limit of 20 bytes (160 bits) on both transmit and receive messages.

The parameter determines whether the configuration data is for Port A or Port B.

The parameter implements portions of the windows serial DCB structure. The implemented structure variables are: fOutxCtsFlow, fRtsControl, fParity and Parity.

fOutxCtsFlow indicates whether the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.

fParity is not used. Parity checking is automatically enabled if Parity (see below) is set to ODDPARITY or EVENPARITY.

Parity sets the parity method. This can be set to the following values: NOPARITY (no parity), ODDPARITY (odd parity), EVENPARITY (even parity) or DATA_BIT_9PARITY (parity bit is used for a ninth data bit). If this member is ODDPARITY or EVENPARITY, parity checking is performed and errors are reported using the function GetParityErrors().

Note: DATA_BIT_9PARITY is a special case. In this case, the ninth bit to be transmitted or received is an additional data bit, not a parity bit. This mode can be set if is set to PORT_RS232 or PORT_CCTALK, but not if one of the polled modes is set. This is because 9-bit parity requires the use of word-wide buffers instead of byte-wide buffers: polled modes do not support word-wide buffers.

Note: To send and receive 9 bit serial data, set Parity = DATA_BIT_9PARITY and use the following functions: Send9BitData(), Receive9BitData() or ReceiveByteWithTimestamp9BitData(). Do not use any other serial functions. Do not use these 9 bit functions with any other value of Parity.

fRtsControl controls how handshaking is handled. This parameter is only relevant when in RS232 mode. The possible values for this member are described below:

Value Description RTS_CONTROL_DISABLE Disables the RTS line when the device is opened and leaves it disabled. RTS_CONTROL_ENABLE Enables the RTS line when the device is opened and leaves it on. RTS_CONTROL_HANDSHAKE Enables RTS handshaking. The driver raises the RTS line when the “type-ahead” (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function. In this implementation, it is treated as RTS_CONTROL_TOGGLE below. RTS_CONTROL_TOGGLE Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.

The parameter must be PORT_RS232, PORT_RS232_POLLED, PORT_CCTALK or PORT_CCTALK_MODE1.

Port B uses TTL levels and signal polarities and has no handshake lines. Therefore, Port B should be set to RTS_CONTROL_DISABLE when port-type is PORT_RS232 or PORT_RS232_POLLED.

The idle condition for port-type PORT_RS232 and PORT_RS232_POLLED is a “1” or marking condition. For Port A, this will be –10V. For Port B, this will be +5V (i.e. TTL). Subject to configuration serial operation may need the presence of an external 12V power supply and may not work if the X-line’s only power source is USB bus power. The absence of an external 12V power supply can be inferred if the current sense input is true and all the parallel outputs are off.

Function Prototype
Method SetConfig:Int( port:Int, config:DCB, _type:Int )

This function programs the duty cycle timing for a specified reel. The duty cycle occurs when the reel is at rest.

The argument specifies the reel number to configure (0-2).

The argument specifies the time (in ms) for the off period of the duty cycle.

The argument specifies the time (in ms) for the on period of the duty cycle.

If the user does not explicitly execute this function, then a default duty cycle of 5ms off/5ms on will be used.

Function Prototype
SetDutyCycle:Int( reelNumber:Byte, offPeriod:Byte, onPeriod:Byte )

Programming Considerations

This function determines the state of an individual output bit during the “off” period of the duty cycle. See the SetOnPeriodOutputBit() function description above.

Function Prototype SetOffPeriodOutputBit:int( usbOutputID:Int, bitNumber:Int, bitState:int )

Programming Considerations The outputs are updated once every millisecond.

Attempts to control outputs that have been assigned to reel stepper motor control will be accepted but ignored.

This function behaves in the same way as SetOnPeriodOutputs() however it allows you to control individual output bits.

The parameter specifies the output block to control. The possible values are stored in the usbOutputId structure, which currently contain the possible outputs: USB_OP_0, USB_OP_1, USB_OP_2, USB_OP_3 and USB_OP_AUX.

The parameter specifies the bit number within the output block to control. These can be bits 0 – 7 for USB_OP_0 – USB_OP_3 and bits 0 – 5 for USB_OP_AUX.

The parameter determines the state of the output during the “on” period of the duty cycle. See SetOnPeriodOutputs() for a more complete description.

Function Prototype SetOnPeriodOutputBit:int( usbOutputID:int, bitNumber:int, bitState:int )

Programming Considerations The outputs are updated once every millisecond.

Attempts to control outputs that have been assigned to reel stepper motor control will be accepted but ignored.

This function determines the brightness for output lamps that have previously been defined using the functions SetOnPeriodOutputs, SetOffPeriodOutputs, SetOnPeriodOutputBit and SetOffPeriodOutputBit.

The parameter defines the brightness with a range 0 – 10.

Function Prototype etOutputBrightness:int( brightness:Byte )

Note: This function actually uses ModifyOutputs(), so a direct call to ModifyOutputs() will be slightly more efficient. It will continue to be supported.

All of the outputs on the USB board may be controlled at once using this function call. The bytes set the outputs as follows (in the order in which they are sent):

· OUTPUT_BIT_OP0-7 · OUTPUT_BIT_OP8-15 · OUTPUT_BIT_OP16-23 · OUTPUT_BIT_OP24-32 · OUTPUT_BIT_AUX0-7

Setting bits will turn the related outputs ON, clearing bits will turn the related outputs OFF.

Function Prototype BOOL SetOutputs( LPBYTE outputs );

Programming Considerations The outputs are updated once every millisecond.

Attempts to control outputs that have been assigned to reel stepper motor control will be accepted but ignored.

This function is provided for legacy support only. Use the function SetOnPeriodOutputs( ) and the related functions (below) to control outputs.

This function sets the serial number for the PIC. The serial number is 8 characters long. This can only be used once. The security of the PIC is controlled by unlockio.lib and this serial number is not related to the security.

Function Prototype SetPicSerialNumber:Int( serial:Byte[] )

If the host software has not requested serial data (using ReceivePolledMessage()) for the defined timeout then the X-line board will inhibit the device. This function is useful for disabling money acceptors in the event of the host PC application crashing.

Three parameters are required for this function:

The parameter determines whether Port A or Port B is used.

The parameter specifies the device number and can take a value 0 – 3.

The parameter specifies the host timeout in seconds. It can take the value 0 – 25.5, where zero disables the timeout. The timeout is disabled by default.

Function Prototype
SetPolledHostTimeout:Int( port:Int, deviceNumber:Byte, timeout:Double )

This function is only available in RS232 Polled Mode or ccTalk Mode 1.

It defines how the reel will be ramped down. Each reel needs a ramp table (which may be different for each reel). Without a ramp table, reel behaviour will be unpredictable.

The variable must be of structure type . This structure is an array of delays, in milliseconds, with the first byte indicating the length of the data table that follows (up to a maximum of 60 data entries). The last millisecond delay value is a power down delay and will not cause the reel to step. It is the amount of time that the reel must remain on full power at the end of the ramp before the motor power is dropped back to a lower level by chopping the drive.

Each delay entry in the table has a maximum value of 255ms.

For example, ramp table of {4,19,20,30,250} will specify a ramp of three steps of 19ms, 20ms and 30ms, followed by a period of 250ms at full power, after which the stepper motor power is reduced by chopping the stepper motor drive.

It defines how the reel will be ramped up. Each reel needs a ramp table (which may be different for each reel). Without a ramp table, reel behaviour will be unpredictable.

The variable must be of structure type . This structure is an array of delays, in milliseconds, with the first byte indicating the length of the data table that follows (up to a maximum of 60 data entries). The first millisecond delay value is a power up delay and will not cause the reel to step. It is the amount of time that the reel must be on full power before stepping can start.

Each delay entry in the table has a maximum value of 255ms.

For example, a ramp up table of {6,200,50,40,30,20,18} will specify a power-up delay of 200ms followed by a ramp of five steps of 50ms, 40ms, 30ms, 20ms and 18ms. It also defines the stepping rate to be used for the remainder of the spin until the reel is ready to ramp down: it will use the last entry in the table, which in this case is 18ms.

Function Prototype
SpinRampUp:Int( reelNumber:Byte, rampUpTable:Byte[] )

Programming Considerations
Do not exceed the maximum table length. Remember that the last entry in the table also defines the spin speed after the ramp up.

This function will spin a stepper motor through a number of steps . Each step size and direction is determined by . The allowed values for are –2 or 2 if full-stepping is required, or –1 or 1 if half-stepping is required.

This command cannot be used until the ramp up and ramp down tables have been defined for the reel. Each reel has its own ramp up and ramp down tables. The number of steps must be greater than the number of steps that are required to perform a complete ramp up and ramp down, otherwise an error will report that not enough steps were requested. The minimum number of steps that can be moved is:

“(number of steps in the ramp up table) + (number of steps in the ramp down table) – 1”

This allows a single step (or single half-step) nudge by using ramp up and ramp down tables with one entry and a spin command of one step. See the sections below describing the ramp table commands for more information on ramps.

The maximum number of steps that can be moved is 32767.

Function Prototype
SpinReels:Int( reelNumber:Byte, directionAndStepSize:Byte, steps:Short )

Programming Considerations
Do not call this function without defining the ramp up and ramp down tables for the reel first. Ensure that the number of steps requested will allow the ramp tables to be carried out, otherwise an error will be reported and the stepper motor will not move.

This function will stop the release of coins from a parallel hopper by turning off the motor.

The parameter specifies the input bit to use for pulse reading. Inputs 0 to 23 may be used.

Function Prototype StopHopperCoinRelease:int( usbInputBitId inputBit )

Programming Considerations This function is only supported on the X10i and X15 boards. It is not supported on the X10 board.

The

Function Prototype
WriteLargeSRAM:Int( address:Int, data:Byte Ptr, totalLength:Short )

Programming Considerations
This is the same as WriteSRAM(), however it is possible to address up to 0x70000 on the X10i instead of 0x7e00 and up to 0xF0000 on the X15. This means that the function can address up to 448k of SRAM on the X10i and 960k on the X15 instead of 32k (as on the X10).

This function is only supported on the X10i and X15 boards. It is not supported on the X10 board.

The