200-338 Part
0.2 Issue
AD Produced
CS Checked
Approved
DRAFT
Page 1 of 226
Date
18/08/08 19/09/08
Notes
Initial Version based on 200-322-1.1 Added new information about device variables to application layer; Added many new application layer API calls.
DRAFT
Page 2 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual 2007-2008 INNOCORE GAMING LIMITED This document may not be copied, reproduced, translated, transmitted or reduced to any printed or electronic medium or to any machine-readable form, or stored in a retrieval system, either in whole or in part, without the prior written consent of INNOCORE GAMING LTD or one of its subsidiaries. Whilst every effort has been made to ensure the accuracy of this document, Innocore Gaming accepts no responsibility for any errors or omissions contained herein. However, if you do discover any inaccuracy in this document, we would be grateful if you would forward the details by fax to: Design & Development Department Innocore Gaming Ltd.
Contact us at: United Kingdom Innocore Gaming Ltd Innocore House KingFisher Way Silverlink Business Park North Shields NE28 9NX Tel +44 (0) 191 262 4844 Fax +44 (0) 191 263 9287 Email: sales@innocoregaming.com
USA
Innocore Gaming Ltd., 10400-4 Pioneer Boulevard, Santa Fe Springs, CA 90670 Tel. +1 (562) 941-5000 Fax. +1 (562) 941-5757 Email: sales@innocoregaming.com
DRAFT
Page 3 of 226
1.1 OVERVIEW........................................................................................................................... 8 1.2 INSTALLATION ..................................................................................................................... 8 1.2.1 WINDOWS ........................................................................................................................ 8 1.2.2 LINUX ............................................................................................................................... 8 1.3 SDK FILES STRUCTURE ....................................................................................................... 8 1.4 SAMPLE CODE .................................................................................................................... 9 2 GETTING STARTED, FREQUENTLY ASKED QUESTIONS ............................................ 10
2.1 PREREQUISITES ................................................................................................................. 10 2.2 FILES ................................................................................................................................ 10 2.3 ERROR CODES .................................................................................................................. 10 2.4 USB AND SERIAL CONVERTERS ........................................................................................ 11 2.5 MONEY CONTROLS ARDAC ELITE .................................................................................. 11 2.6 FREQUENTLY-ASKED QUESTIONS ...................................................................................... 12 2.6.1 DO I USE THE CCTALK APPLICATION LAYER OR THE CCTALK NATIVE API? ........................ 12 2.6.2 HOW DO I FIND OUT WHICH BILLS/NOTES ARE PROGRAMMED? ....................................... 12 2.6.3 HOW DO I ACCEPT OR DECLINE (REJECT) SPECIFIC NOTES?............................................. 12 2.6.4 HOW DO I PROGRAM THE BILL ACCEPTOR TO (NOT) USE ESCROW-MODE?....................... 13 2.6.5 HOW DO I PROGRAM THE BILL ACCEPTOR TO (NOT) USE THE STACKER? ......................... 13 2.6.6 HOW DO I ACCEPT BARCODES?...................................................................................... 13 2.6.7 HOW CAN I PROGRAM IN A BILL/NOTE TABLE? ................................................................. 14 2.6.8 HOW CAN I PROGRAM IN NEW FIRMWARE? ...................................................................... 14 2.6.9 HOW DO I USE ENCRYPTED DATA OR 16-BIT CHECKSUMS FOR MY ARDAC ELITE? ............ 15 2.6.10 MY APPLICATION ALREADY HAS AN EVENT-DRIVEN LOOP: WHAT DO I DO? ..................... 15 3 CCTALK APIS.................................................................................................................... 16
3.1 SYSTEM FUNCTIONS .......................................................................................................... 17 3.1.1 DGSYS_ERROR_TO_TEXT: CONVERT AN ERROR MESSAGE TO A TEXT STRING.................... 17 3.2 CCTALK APPLICATION LAYER ............................................................................................ 18 3.2.1 CCTALK_APP_INIT: INITIALISE APPLICATION LAYER ........................................................... 18 3.2.2 DG_CCTALK_APP_EVT_HANDLER: CUSTOMER EVENT HANDLING FUNCTION ............ 20 3.2.3 DG_CCTALK_APP_EVT_CODE, DG_CCTALK_APP_EVT_TYPE............................. 23 3.2.4 DG_CCTALK_APP_DEVICE_INFO: DEVICE INFORMATION .......................................... 30 3.2.5 CCTALK_APP_ADD_LINK: ADD A LINK FOR APPLICATION LAYER MONITORING .................... 33 3.2.6 CCTALK_APP_RUN: START THE CCTALK APPLICATION LAYER EVENT-LOOP ...................... 36 3.2.7 CCTALK_APP_FINISH: TERMINATE THE DEVICE MONITORING LOOP ................................... 38 3.2.8 CCTALK_APP_GET_DEVICE_INFO: GET A DISCOVERED DEVICES INFORMATION ................ 39 3.2.9 CCTALK_APP_ENABLE_DEVICE: ENABLE A DEVICE ........................................................... 41 3.2.10 CCTALK_APP_DISABLE_DEVICE: DISABLE A DEVICE ....................................................... 43 3.2.11 CCTALK_APP_EVENT_NAME: TRANSLATE AN EVENT CODE INTO READABLE TEXT ........... 45 3.2.12 CCTALK_APP_ACCEPT_BILL: ACCEPT A BILL IN ESCROW POSITION ................................. 47 3.2.13 CCTALK_APP_REJECT_BILL: REJECT A BILL IN ESCROW POSITION.................................. 49 3.2.14 CCTALK_APP_LOAD_BILL_TABLE: LOAD A NEW BILL TABLE ............................................ 50
DRAFT
Page 4 of 226
DRAFT
Page 5 of 226
DRAFT
Page 6 of 226
4.1 COMPONENT INSTALLATION ............................................................................................. 204 4.2 COMPONENTS ................................................................................................................. 207 4.2.1 MONEY CONTROLS CCTALK SDK CCTALK PROTOCOL ................................................... 208 4.2.2 MONEY CONTROLS CCTALK SDK SAMPLE PROGRAMS .................................................. 209 4.2.3 MONEY CONTROLS CCTALK SDK UTILITY PROGRAMS ................................................... 210 5 5.1 COMMAND LINE UTILITIES............................................................................................ 211 CCUTIL ........................................................................................................................... 211 INNOCORE GAMING LOCATIONS ............................................................. 226
APPENDIX 1
DRAFT
Page 7 of 226
1 INTRODUCTION
1.1 OVERVIEW
This manual describes the ccTalk SDK and constituent functions, utilities and other features. The targeted audience of this product is software developers. The purpose of the SDK is to provide a developer with functions that can be easily used to communicate with different peripheral devices used in gaming industry such as coin hoppers, printers, bill acceptors and coin mechanisms.
1.2
INSTALLATION
1.2.1 WINDOWS Windows version of ccTalk SDK comes with an installer called setup.exe. Run the installer and follow the on-screen instructions. By default the ccTalk SDK files will be installed into <System drive>:\Program Files\Money Controls\ccTalk SDK. 1.2.2 LINUX Linux version of ccTalk SDK comes as GNU-zipped tar file called connector_install_1.0.1.x_linux_i686.tar.bz2. Extract the contents of the file into any directory you prefer using the following command:
# tar jxvf connector_install_1.0.1.x_linux_i686.tar.bz2
You will end up with directories called ./lib, ./include and ./tests. ./lib and ./include directories contain the libraries and C header files respectively. ./tests directory contains sample code. There is also script file called install.sh. If you run this file then the files in ./lib directory will be copied over into /usr/lib, ./include directory will be copied over into /usr/include and ./tests directory will be copied over into /usr/src/Innocore/DPXConnector. You will need root privileges in order for this script to run successfully.
1.3
After SDK installation the installation directory contains the following directories:
DRAFT
Page 8 of 226
The include directory contains the header files, the lib directory contains the protocol and link libraries and the tests directory contains the sample code for every protocol library.
1.4
SAMPLE CODE
As it was mentioned earlier in section 1.2 the demos directory contains sample code for every protocol library provided by SDK. Linux users can just issue make command in order to build the sample executable. After make finishes there will be two directories: Debug and Release which contain debug and release versions of the sample code. The directories will also contain the stream_rs.so lib file and the protocol-specific library used by the sample code. If you havent copied all the library files into one of the directories pointed by LD_LIBRARY_PATH environment then add current directory to the LD_LIBRARY_PATH variable:
# export LD_LIBRARY_PATH = $LD_LIBRARY_PATH:./
This tells the OS to search for the needed libraries in the directory, where you will be running the sample code from. Windows users are provided with VC6 studio workspace files. Just build the sample code and you are ready to run the executables.
DRAFT
Page 9 of 226
This manual is written for the C/C++ programmer/developer. It assumes the reader is familiar with C/C++ programming, including pointers, Fabstract and aggregated data types and is able to roughly understand how programs, libraries and the symbols (the names for variables and functions) are linked together.
2.2
FILES
In order to successfully compile your code please make sure that you have included the following header files:
connector_sdk.h ccTalk.h cctalk_app.h
Libraries (Windows)
ccTalk.dll ccTalk.lib (import library)
Libraries (Linux)
libccTalk.so
2.3
ERROR CODES
All the API functions return date of type DG_ERROR. The error code values are defined in the header file dg_error.h. The full error code values which are returned by API functions consist of two parts: the first 16 bits define the error code itself and the other 16 bits define the module which generated the error. There are two helper macros defined in dg_error.h file:
DG_IS_SUCCESS(<error code>) The macro returns TRUE if the function returned
error code. The function dgsys_error_to_text() is often more helpful it converts any error code expressed as a DG_ERROR into a human readable text string.
DRAFT
Page 10 of 226
2.4
An increasing number of devices supporting ccTalk communication have USB connectors too. This applies, for example, to the MoneyControls Ardac Elite bill acceptor; additionally some devices with standard ccTalk communication ports can be attached to a computer without ccTalk ports by using a USB-to-serial converter. A suitable software driver must be loaded for this to work. For MoneyControls devices, a suitable Windows driver by FTDI is supplied with the device. This should be installed according to the driver and the peripheral instructions. For MoneyControls devices to be used with the GNU/Linux operating system, the ftdi_sio driver should be loaded with the vendor and product parameters set to the USB vendor-id and product-id respectively. This information can be determined by using the lsusb command. For example,
# lsusb Bus 004 Device 001: Bus 003 Device 001: Bus 002 Device 001: Bus 001 Device 003: Bus 001 Device 001: # modprobe ftdi_sio # ID 0000:0000 ID 0000:0000 ID 0000:0000 ID 106f:0001 Money Controls ID 0000:0000 vendor=0x1067 product=0x1
The Linux serial port device is called /dev/ttyUSBn; where n starts at 0 and increases monotonically for each USB serial device configured.
2.5
This device can be connected either to traditional RS-232-based serial communications lines (either COM3 and COM4 for ccTalk or another COM port for ID003 protocol) or to a USB port. When using traditional ccTalk communications, the baud-rate to use is 9600. When using USB communications, an appropriate USB-to-Serial converter driver must be loaded (see 2.4 above). The USB vendor ID for this device is 0x1067 and the device ID is 0x0001. The standard baud rate for this communication line is 921600. The default ccTalk address for this device is 40.
DRAFT
Page 11 of 226
2.6
FREQUENTLY-ASKED QUESTIONS
The following sections deal with how to perform specific tasks with the ccTalk application layer and API. 2.6.1 DO I USE THE CCTALK APPLICATION LAYER OR THE CCTALK NATIVE API? This depends upon your need. To get started quickly, use the application layer described in section 3.2. If your application doesnt already have its own main processing loop then you may also use the application layer. However, if your own application architecture precludes using the application layers polling loop then you may have to use the ccTalk native API to discover devices and poll these devices for their events. 2.6.2 HOW DO I FIND OUT WHICH BILLS/NOTES ARE PROGRAMMED? There are two ways to determine the contents of the bill/note table. From the Linux command line or the Windows command prompt, you can use the ccutil program (see section 5) thus:
C:\>ccutil p COM3 a 40 -show-bills
Where COM3 is the port to which the bill/note validator connector and 40 is its ccTalk protocol address. On Linux, the COM3 device will likely be /dev/ttyUSB0 or /dev/ttySx. See the previous sections 2.4 and 2.5 for more information. In a C/C++ program, you may use either the ccTalk native API function cctalk_req_bill_id(). 2.6.3 HOW DO I ACCEPT OR DECLINE (REJECT) SPECIFIC NOTES? Using the ccTalk application layer, use the API function cctalk_app_reject_bill() to reject the bill just inserted into a bill/note validator or the function cctalk_app_accept_bill() to accept the bill. Most bill/note validators automatically reject notes that are not known (not in the programmed bill table) so that when an event is received documenting an invalid bill, there is no need to reject the note explicitly using cctalk_app_reject_bill(). These methods also apply to coupons bearing bar-codes recognised by the device in question.
DRAFT
Page 12 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual 2.6.4 HOW DO I PROGRAM THE BILL ACCEPTOR TO (NOT) USE ESCROW-MODE? The ccTalk native API function cctalk_cmd_modify_bill_op_mode() (command 153) can be used to change this. Since the parameter to this command controls also the use of a stacker, you should read back the existing operating mode word using cctalk_req_bill_op_mode() in order to avoid change the previous setting, unless you wish to set both capabilities at once. For example
unsigned char uchOpMode; DG_ERROR iResult; iResult = cctalk_req_bill_op_mode(handle, address, &uchOpMode); if (!DG_IS_SUCCESS(iResult)) { // Error handling } // Enable the escrow mode. // uchOpMode |= 2; iResult = cctalk_cmd_modify_bill_op_mode(handle, address, uchOpMode); if (!DG_IS_SUCCESS(iResult)) { // Error handling }
2.6.5 HOW DO I PROGRAM THE BILL ACCEPTOR TO (NOT) USE THE STACKER? Configuring use of the stacker is nearly identical to configuring use of escrow mode. Bit 0 of the byte configuring the bill operating mode is reserved for configuring the stacker operating. 2.6.6 HOW DO I ACCEPT BARCODES? The Money Controls Ardac Elite bill/note validator is pre-programmed to recognise and scan a range of different types of bar-code common to various target markets. In the unlikely event your bar-codes are not automatically recognised, please contact your Money Controls sales representative for assistance. Programmatically, acceptable bar-codes result in the Ardac Elite issuing an event with data {ResultA,ResultB} = {0,20}. (See Table 7 in the ccTalk Generic Specification available from http://www.ccTalk.org.)
DRAFT
Page 13 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual When using the application layer, your event handler receive an event of type DG_CCTALK_APP_EVT_BARCODE_INSERTED before receiving a further event of type DG_CCTALK_APP_EVT_BILL_IN_ESCROW or (IN_STACKER if you have escrow mode disabled) with the iBillAmount event structure member set to 0. When use the native ccTalk API, the event table returned by cctalk_req_bill_events() will contain an event of code DGC_CCTALK_BEVT_S_BARCODE followed by DGT_CCTALK_BEVT_C_STACKED or DGT_CCTALK_BEVT_C_ESCROWED. 2.6.7 HOW CAN I PROGRAM IN A BILL/NOTE TABLE? There are two ways to program in a bill/note table. From the Linux command line or the Windows command prompt, you can use the ccutil program (see section 5) thus:
C:\>ccutil p COM3 a 40 -table-upload file.tab
Where COM3 is the port to which the bill/note validator connector and 40 is its ccTalk protocol address. On Linux, the COM3 device will likely be /dev/ttyUSB0 or /dev/ttySx. See the previous sections 2.4 and 2.5 for more information. In a C/C++ program, you may use either the API function cctalk_cmd_upload_bill_table() or the set of functions cctalk_cmd_begin_bill_upgrade(), cctalk_cmd_upload_bill_table_data() and cctalk_cmd_finish_bill_upgrade(). 2.6.8 HOW CAN I PROGRAM IN NEW FIRMWARE? There are two ways to program in a bill/note table. From the Linux command line or the Windows command prompt, you can use the ccutil program (see section 5) thus:
C:\>ccutil p COM3 a 40 -firmware-upload firmware.bin
Where COM3 is the port to which the bill/note validator connector and 40 is its ccTalk protocol address. On Linux, the COM3 device will likely be /dev/ttyUSB0 or /dev/ttySx. See the previous sections 2.4 and 2.5 for more information. In a C/C++ program, you may use either the API function cctalk_cmd_upload_firmware() or the set of functions cctalk_cmd_begin_firmware_upgrade(), cctalk_cmd_upload_firmware_data() and cctalk_cmd_finish_firmware_upgrade().
DRAFT
Page 14 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual 2.6.9 HOW DO I USE ENCRYPTED DATA OR 16-BIT CHECKSUMS FOR MY ARDAC ELITE? Neither encrypted data nor 16-bit checksums are supported in this release of the ccTalk API. 2.6.10 MY APPLICATION ALREADY HAS AN EVENT-DRIVEN LOOP: WHAT DO I DO? Two choices available in this event: On both Windows and Linux, you may create a thread within your application to accommodate the ccTalk application layer polling loop. It is beyond the scope of this manual to describe how this is done, although it is not technically demanding. If your application cannot accommodate a separate thread then you will have to use the ccTalk native API (see section 3.3) and discover devices manually and poll them for their events at an interval of your choice.
DRAFT
Page 15 of 226
3 CCTALK APIS
The library provides functions that enable communication with devices using ccTalk protocol. Please visit libdgccTalk Files C Header files
ccTalk.h cctalk_app.h
Libraries (Windows)
ccTalk.dll ccTalk.lib (import library)
Libraries (Linux)
libccTalk.so
In order to successfully compile your code please make sure that you have included the following header files: connector_sdk.h If you are writing your application in C++ please make sure that you have specified Connector SDK namespace:
#include <connector_sdk.h> #include <ccTalk.h> using namespace __CONNECTOR_SDK;
DRAFT
Page 16 of 226
3.1
3.1.1
SYSTEM FUNCTIONS
DGSYS_ERROR_TO_TEXT: CONVERT AN ERROR MESSAGE TO A TEXT STRING
Definition
const char *dgsys_error_to_text(IN DG_ERROR error_code);
Parameters
Error_code
This is an error code returned by any other ccTalk application layer function, command or request returning a DG_ERROR code.
Description This function converts the error code in error_code into a text string of the form %s layer error 0x%x: %s where the first %s is the name of the subsystem producing the error, the %x is the error code error_code and the final %s is the specific error string for the subsystem. Return Value The return value is a pointer to NUL-terminated C string showing the error text for the error number in error_code. Errors None. Notes If the error code is invalid, a valid text string is still returned stating that the code is unknown and quoting the error code in hexadecimal. Example
#include <connector_sdk.h> #include <ccTalk.h> iResult = cctalk_app_init(NULL); if(!DG_IS_SUCCESS(iResult)) { printf(Couldnt intialise application layer: %s\n, dgsys_error_to_text(iResult)); }
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 17 of 226
3.2
The ccTalk application is a higher-level approach to ccTalk device communication than is available using solely the ccTalk command/request API (see section 3.3) and provides a somewhat simpler interface than the latter. You may still, however, use command/request API functions if necessary, only a few of which conflict with use of the application layer. These conflicts are pointed out where appropriate in the sections following. The following devices are supported in this release. 3.2.1 Money Controls Internationals Ardac Elite (Ardac6) Bill/note Validator.
CCTALK_APP_INIT: INITIALISE APPLICATION LAYER
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_init(DG_CCTALK_APP_EVT_HANDLER pfnHandler); typedef void (*DG_CCTALK_APP_EVT_HANDLER) (PDG_CCTALK_APP_EVT pEVT);
Parameters pfnHandler
A pointer to a function to be called when new events are available. The function takes a single parameter which is a pointer to a structure of type DG_CCTALK_APP_EVT; it returns no data. This parameter may not be NULL.
Description cctalk_app_init() initialises the application layer for ccTalk operations. Errors
DGERROR_OK
The operation completed successfully. The application layer has already been initialised and may not be reinitialized.
DRAFT
Page 18 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Notes The event codes and handling of events is covered in the following section. Example
#include #include #include #include <connector_sdk.h> <connector_sdk.h> <ccTalk.h> <cctalk_app.h>
using namespace __CONNECTOR_SDK; void my_event_handler(PDG_CCTALK_APP_EVT *pEVT) { ... } ... DG_ERROR iResult = cctalk_app_init(my_event_handler); if(!DG_IS_SUCCESS(iResult)) { fprintf(stderr, Couldnt initialise application layer: %s\n, dgsys_error_to_text(iResult)); // other error handling code here // }
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 19 of 226
} DG_CCTALK_APP_EVT, *PDG_CCTALK_APP_EVT;
Description The data type DG_CCTALK_APP_EVT (and its associated pointer type PDG_CCTALK_APP_EVT) are used to describe events being delivered to the customer application. The fields of the event structure have the following meanings.
eEventCode eEventType
This is the code of the event delivered. See the event codes described in 3.2.3. This is the type of the event delivered. See the event types described in 3.2.3.
DRAFT
Page 20 of 226
This is the time at which the event was received by the application layer. (Due to delays induced by the communications protocol, the response time of the device and latencies in the host operating system, this time will rarely be the same as the time at which the event occurred on the device reporting it. This is the handle for the link upon which the device is connected which reported the event. This value may be passed as the iHandle parameter to all ccTalk API functions which require one. This is the ccTalk address for the device which reported the event. This value may be passed as the device destination address parameter (uchAddress or uchDstAddress) to all ccTalk API functions which require one. For events which pertain to bills or coupons being inserted into or stacked by a bill/note validator, this structure contains information about the bill in the same format as returned by cctalk_req_bill_id(). For events which pertain to bills or coupons being inserted into or stacked by a bill/note validator, this member contains the corrected value for the bill, taking into account all bill and country scaling factors. This member is populated by the ccTalk application layer and is for internal use. It should not be modified.
iHandle
uchAddress
sBillInfo
iBillAmount
_private
The union uData exists in this structure to represent any ancillary data that may be required to be reported for the current event.
uData.lData uData.iData uData.ucArray uData.cString uData.pvoid
Data represented as a long integer. Data represented as a regular integer. Data represented as a byte (unsigned char) array of up to 128 bytes. A pointer to a string elsewhere in memory. A void pointer to something somewhere else in memory.
Generally, your event handling function need only examine a few fields of the event structure namely eEventType, eEventCode and, if necessary, iBillAmount. Rarely will it be necessary to use the other members or use ccTalk API commands.
DRAFT
Page 21 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Notes The memory associated with the event being delivered may be re-used for future events and, as such, should not be referenced after the event handler has completed. Example Please see dgcctalk_app_demo.cpp for more information how to construct an event handler.
DRAFT
Page 22 of 226
DRAFT
Page 23 of 226
Description These two enumerated types are essential for understanding what event and what type of event is being delivered. The event type enumeration values have the following meanings.
DG_CCTALK_APP_EVT_TYPE_NONE DG_CCTALK_APP_EVT_CREDIT
This value exists for completions sake and should not be seen. The event-type means a valid bill or coupon has been accepted by the a bill acceptor and sent to the stacker. The event-type means a valid bill or coupon has been inserted into a bill acceptor and is being held in escrow for further processing. This event-type pertains to events which are merely informational and on which action need not necessarily be taken. This event-type demarks the rejection of a bill or coupon and its return to the customer. This event-type pertains to events that mark an error during device operations. This event-type demarks cases where the device reports that an attempt at fraud has been made.
DG_CCTALK_APP_EVT_PENDING_C REDIT
DG_CCTALK_APP_EVT_STATUS
DG_CCTALK_APP_EVT_REJECT
DG_CCTALK_APP_EVT_ERROR DG_CCTALK_APP_EVT_FRAUD
DRAFT
Page 24 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual The event type enumeration values have the following meanings. Except where indicated otherwise, the iHandle and uchAddress members of the event structure are populated with the link ID and destination address of the device concerned.
DG_CCTALK_APP_EVT_CODE_NONE
This event exists merely for completions sake as a marker that no event has occurred. It should never be seen in a delivered event.
DG_CCTALK_APP_EVT_OPENED_LINK
This event is sent when a link is successfully opened for the first time. The iHandle member of the event structure can now be used with ccTalk request or command functions. The uchAddress member is set to 1 the address of the ccTalk host device.
DG_CCTALK_APP_EVT_FOUND_DEVICE
This event is delivered when a new device is found on an open link. One such event is delivered for each device found on a link when cctalk_app_add_link() is invoked. The iHandle and uchAddress members of the event structure are populated with the link ID and destination address of the device just discovered. The application may invoke cctalk_app_get_device_info() to find out more information about the device which was discovered. For bill/note validators, the ccTalk application layer loads all of the bill and country code information from the device prior to delivering this event. Other functions such as cctalk_app_load_firmware() cctalk_app_load_note_table() may also be invoked at this stage. and
This is also the correct time in the application layer start-up to determine whether other device settings (such as individual note inhibits, whether to enable escrow mode and self-test results) need to be adjusted.
DG_CCTALK_APP_EVT_START_DEVICE
This event is delivered when cctalk_app_run() is invoked just prior to regular polling of the device. The iHandle and uchAddress members of the event structure are populated with the link ID and destination address of the device being started. For bill/note acceptors, this is the time at which functions such as cctalk_cmd_master_inhibit_status() should be invoked. The ccTalk application layer itself takes no other action to start devices other than to deliver this event.
DG_CCTALK_APP_EVT_STOP_DEVICE
DRAFT
Page 25 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual This event is delivered when cctalk_app_run() is about to finish because the function cctalk_app_finish() was invoked. Once this event has been delivered and the event handler has completed, the ccTalk application layer makes a final attempt to shutdown each device. For bill/note validators, the master inhibit is set and so the device is disabled.
DG_CCTALK_APP_EVT_DEVICE_NOT_RESPONDING
This event is delivered when a device stops responding to its regular polling. All devices found are subject to a regular simple ccTalk poll. After N failed polls, this event is delivered once only until the device starts responding again.
DG_CCTALK_APP_EVT_DEVICE_RESPONDING
This event is delivered when a device starts responding again to its regular polling. After the first successful re-poll, this event is delivered once only until the device stops responding again.
DG_CCTALK_APP_EVT_DEVICE_POWER_CYCLE
This event is delivered if the device has been power-cycled. For bill/note validators this happens by detecting when the devices event count reverts to zero.
DG_CCTALK_APP_EVT_BILL_IN_ESCROW
This event is delivered when a valid note or coupon is inserted into a bill/note validator and the validator has been programmed for escrow mode (as opposed to simply sending each note/coupon directly to the stacker). The iBillAmount member of the event has the corrected value of the inserted bill set. The sBillInfo member also has the bill acceptors native bill information. If a coupon has been entered with a valid bar-code, then the iBillAmount member will be zero. A seperate event notifying the detection of a bar-code will already have been delivered.
DG_CCTALK_APP_EVT_BILL_IN_STACKER
This event is delivered when a valid note or coupon has been routed to the devices stacker (if fitted). This happens either if the validator has been programmed to simply send each note/coupon directly to the stacker, or if the note was previous escrowed and validated and the application then specifically routed the bill to the stacker. Doc. ref. 200-338_0.1 DRAFT Page 26 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual The iBillAmount member of the event has the corrected value of the inserted bill set. The sBillInfo member also has the bill acceptors native bill information. If a coupon was entered with a valid bar-code, then the iBillAmount member will be zero. A seperate event notifying the detection of a bar-code will already have been delivered. Note that in the case where escrow mode is enabled and a bar-code is detected, the bar-code event is delivered only once.
DG_CCTALK_APP_EVT_BILL_INHIBITED
This event is delivered when a note has been inserted into a bill/note validator and the validator has been programmed (either programmatically or via physical switches present on the device hardware) to inhibit that note. It is not possible to determine which note was entered.
DG_CCTALK_APP_EVT_BILL_PULLED
This event is delivered when an attempt is made to pull the note back out of the bill acceptor while it is being inserted. (This is a fraud attempt which is based around having the device validate a bill and report the successful validation without submitting the bill to the devices stacker.)
DG_CCTALK_APP_EVT_BILL_TAMPERED
This event is delivered when a bill is submitted to a bill/note validator which is considered to be the subject of tampering.
DG_CCTALK_APP_EVT_BILL_INVALID
This event is delivered when the bill submitted by the customer does not match any programmed bill in the bill/note validators tables or a coupon is submitted which has no valid bar-code.
DG_CCTALK_APP_EVT_BILL_FAILED_TRANSPORT
This event is delivered when a bill/note validator fails to wind the bill/coupon into its detection mechanism.
DG_CCTALK_APP_EVT_BILL_RETURNED
This event is delieverd when a successful upgrade of the devices firmware has been completed. Doc. ref. 200-338_0.1 DRAFT Page 27 of 226
This event is delieverd when an upgrade of the devices firmware has failed.
DG_CCTALK_APP_EVT_BILLTABLE_LOADED
This event is delieverd when loading bill/note tables into a bill/note validator has succeeded.
DG_CCTALK_APP_EVT_BILLTABLE_LOAD_FAILURE
This event is delieverd when loading bill/note tables bill/note tables into a bill/note validator has failed.
DG_CCTALK_APP_EVT_BARCODE_INSERTED
This event is delivered when a coupon bearing a bar-code is entered into a bill/note validator. Please refer to the manufacturers technical manuals for information about the permitted formats of bills. The barcode event is reported once only before an event notifying that a coupon has been inserted and is not repeated if an escrowed coupon is later transferred to the stacker. The uData.ucArray member of the event structure contains an ASCII string representing the validation digits of the bar code.
DG_CCTALK_APP_EVT_STACKER_OK
This event is delivered when the stacker of a bill/note validator is now in acceptable status, having previously been jammed or faulty or full.
DG_CCTALK_APP_EVT_STACKER_JAMMED
This event is delivered when the stacker mechanism of a bill/note validator has jammed.
DG_CCTALK_APP_EVT_STACKER_REMOVED
This event is delivered when the stacker tray of a bill/note validator has been removed.
DG_CCTALK_APP_EVT_STACKER_INSERTED
This event is delivered when the stacker tray of a bill/note validator has been inserted.
DG_CCTALK_APP_EVT_STACKER_FAULTY
This event is delivered when the stacker mechanism of a bill/note validator is faulty.
DG_CCTALK_APP_EVT_STACKER_FULL
This event is delivered when the stacker tray of a bill/note validator is full.
DG_CCTALK_APP_EVT_STRING_FRAUD
DRAFT
Page 28 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual This event is delivered when a bill/note validator detects string fraud. Consult the device manufacturers technical manuals for further information.
DG_CCTALK_APP_EVT_ANTISTRING_ERROR
This event is delivered when a bill/note validator detects the anti-string fraud mechanism has an error. Consult the device manufacturers technical manuals for further information.
DG_CCTALK_APP_EVT_OPTO_FRAUD
This event is delivered when a bill/note validator detects optical fraud. Consult the device manufacturers technical manuals for further information. Notes The memory associated with the event being delivered may be re-used for future events and, as such, should not be referenced after the event handler has completed. At present, only events associated with bill/note validators are represented.
DRAFT
Page 29 of 226
DG_CCTALK_APP_DEVICE_COINMECH, // coin acceptor/validator DG_CCTALK_APP_DEVICE_BNV, // Bill/note acceptor/validator _DG_CCTALK_APP_DEVICE_INVALID // MARKS END OF ENUMERATOR TYPE } DG_CCTALK_APP_DEVICE_TYPE; typedef struct _DG_CCTALK_APP_DEVICE_INFO { int unsigned char DG_CCTALK_APP_DEVICE_TYPE char char char char char char char unsigned long iHandle; uchAddress; eType; sManufacturer[256]; sCategory[256]; sModel[256]; sFirmware[256]; sBuildCode[256]; sSerialNumber[256]; sCommsRevision[256]; ulRomChecksum;
Description The data type DG_CCTALK_APP_DEVICE_INFO (and its associated pointer type PDG_CCTALK_APP_DEVICE_INFO) are used to describe a device discovered by the ccTalk application layer. The fields of the event structure have the following meanings.
DRAFT
Page 30 of 226
This is the handle for the link upon which the device is connected which reported the event. This value may be passed as the iHandle parameter to all ccTalk API functions which require one. This is the ccTalk address for the device is connected which reported the event. This value may be passed as the device destination address parameter (uchAddress or uchDstAddress) to all ccTalk API functions which require one. This records the type of device discovered. This records the manufacturers name string returned by the device on receiving ccTalk command #246. This records the equipment category string returned by the device on receiving ccTalk command #245. This records the devices product code string returned by the device on receiving ccTalk command #246. This records the software version string returned by the device on receiving ccTalk command #241. This records the device build code string returned by the device on receiving ccTalk command #192. This records the devices serial number returned by the device on receiving ccTalk command #242. The four bytes returned are combined into a single unsigned integer and then formatted into the buffer. This string records the ccTalk communications revision as returned by ccTalk command #4. The string is formatted thus: major-revison.minor-revision (release level) This records the device ROM checksum data returned by the device on receiving ccTalk command #197. This array of unsigned characters contains the variableset returned by the device. This denotes how many characters of data in ucVariables are valid.
uchAddress
sCommsRevision
Notes An internal copy of this structure is initialized to zero when each device is found. If for some reason a given string couldnt be obtained then that field will contain a zero-length string. Doc. ref. 200-338_0.1 DRAFT Page 31 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Example Please see dgcctalk_app_demo.cpp for more information how to obtain and use device information.
DRAFT
Page 32 of 226
3.2.5
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_add_link(char *szPortSpec);
Parameters szPortSpec
The communications specification for the port on which to open ccTalk communications. This parameter may not be NULL.
Description cctalk_app_add_link() opens ccTalk communications on a give com port and scans for ccTalk compatible devices connected to it. For each device found, that devices manufacturer, product-name, build-code, serial-number, firmwareversion and ROM checksum are obtained before an event of type DG_CCTALK_APP_EVT_FOUND_DEVICE is delivered. The szPortSpec parameter is composed from key=value pairs delimted by a comma (,). The following parameters are accepted.
port
The value specifies the serial port that needs to be used. For MS Windows it is the name of the com ports: COM1, COM2 etc. For Linux it is the name of the ttyS files in the dev directory: /dev/ttyS0, /dev/ttyS1 etc. This parameter must be specified. The value specifies the baud rate. The possible values are: 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000. If not specified, the baud-rate defaults to 9600. The value specifies the number of data bits. The possible values are: 5,6,7,8. If not specified, the byte size is 8 bits. Specifies the number of stop bits to be used: 1 or 2. If not specified then 1 stop bit is used. Specifies the parity scheme to be used: no, even or odd. If not specified then no parity bit is used.
baudrate
DRAFT
Page 33 of 226
Sets hardware flow control. If set to 1 then hardware flow control is enabled. This works if the CTS on the computer is connected to RTS on the peripheral device and RTS on the computer is connected to CTS on the peripheral device. If not specified then no hardware flow control is used. Sets XON character used for software flow control. If either XON or XOFF character have been specified then software flow control is enabled. <optional parameter> Sets XOFF character used for software flow control. If either XON or XOFF character have been specified then software flow control is enabled. <optional parameter>
xonchar
xoffchar
Errors
DGERROR_OK
The operation completed successfully. Memory could operation. not be allocated for this
Notes The event codes and handling of events is covered in the section 3.2.3. ctalk_app_add_link() operates by calling cctalk_open_link() and then using cctalk_cmd_address_poll(); error codes returned by both these functions are also possible in addition to those listed above. Example
#include <connector_sdk.h> #include <ccTalk.h> #include <cctalk_app.h> using namespace __CONNECTOR_SDK; void my_event_handler(PDG_CCTALK_APP_EVT *pEVT); ... DG_ERROR iResult = cctalk_app_init(my_event_handler); if(!DG_IS_SUCCESS(iResult)) { // Error handling code here } // Configure the link suitable for a Money Controls Ardac Elite.
DRAFT
Page 34 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 35 of 226
3.2.6
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_run(void);
Parameters None. Description cctalk_app_run() starts the main event loop of the ccTalk application layer. For each device discovered on each link added, an event of code DG_CCTALK_APP_EVT_START_DEVICE is first delivered. The ccTalk application now goes into polling mode in which each device is polled at regular intervals with events delivered to the registed event handler when these are received by the polling function. Once the normal polling operations have begun, cctalk_app_run() does not return to the caller unless cctalk_app_finish() is called. Once the application has been instructed to terminate, for each device discovered on each link added, an event of code DG_CCTALK_APP_EVT_STOP_DEVICE is then delivered. Errors
DGERROR_OK DGERROR_NODEVICES
The operation completed successfully. No Links have been added or there are no devices discovered on those links.
Notes The event codes and handling of events is covered in the section 3.2.3. You should not use cctalk_req_bill_events (ccTalk command code 159) when using this function; if you do, then events may be missed by the application loop. Example
#include <connector_sdk.h> #include <ccTalk.h> #include <cctalk_app.h> using namespace __CONNECTOR_SDK;
DRAFT
Page 36 of 226
void my_event_handler(PDG_CCTALK_APP_EVT *pEVT); ... DG_ERROR iResult = cctalk_app_init(my_event_handler); if(!DG_IS_SUCCESS(iResult)) { // Error handling code here } // Configure the link suitable for a Money Controls Ardac Elite. // iResult = cctalk_app_add_link(port=COM3,baudrate=921600); if(!DG_IS_SUCCESS(iResult)) { // Error handling code here } // Configure the link suitable for a Money Controls Ardac Elite. // iResult = cctalk_app_run(); if(!DG_IS_SUCCESS(iResult)) { // Error handling code here }
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 37 of 226
3.2.7
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_finish(void);
Parameters None Description This function causes the device monitor loop started by calling cctalk_app_run() to terminate. cctalk_app_run() first shutdown each device before returning to its caller. Errors
DGERROR_OK
Notes None. Example Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 38 of 226
3.2.8
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_get_device_info(PDG_CCTALK_APP_EVT pEVT, PDG_CCTALK_APP_DEVICE_INFO pDI);
An event containing the link and address information for the device concerned. A pointer to an instance of DG_CCTALK_APP_DEVICE_INFO into which the devices information will be placed. See 3.2.4 for a description of this data type.
Description cctalk_app_get_device_info() returns a copy of the device information obtained when the device was discovered. This information is obtained prior to an event of type DG_CCTALK_APP_EVT_FOUND_DEVICE being delivered. Errors
DGERROR_OK
The operation completed successfully. presented by the application or has been corrupted.
DRAFT
Page 39 of 226
iError = cctalk_app_get_device_info(pEVT, &sDeviceInfo); if (!DG_IS_SUCCESS(iError)) { // Error handling } else { printf(Event from device %s at address %d on link %d\n, pDI->sModel, pDI->uchAddress, pDI->iHandle); } // Do other event handling stuff now. }
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 40 of 226
3.2.9
Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_enable_device(PDG_CCTALK_APP_EVT pEVT);
Parameters pEVT
An event containing the link and address information for the device concerned.
Description cctalk_app_enable_device() attempts to enable a given ccTalk device. The definition of enabling differs with each device equipment category. At present, enabling is only defined for Bill/Note validators, where this operation amounts to clearing (disabling) the devices master inhibit flag. Errors
DGERROR_OK
DRAFT
Page 41 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 42 of 226
Parameters pEVT
An event containing the link and address information for the device concerned.
Description cctalk_app_enable_device() attempts to disable a given ccTalk device. The definition of disabling differs with each device equipment category and usually the opposite operation to enabling the device. At present, enabling and disabling is only defined for Bill/Note validators, where disabling amounts to setting (enabling) the devices master inhibit flag so that it will not accept bills or coupons. Errors
DGERROR_OK
DRAFT
Page 43 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 44 of 226
Parameters codeEVT
Description cctalk_app_get_event_name() converts an event code into a human-readable text string. Errors If the event code code is not a valid event code then a string of format Invalid event code #%d is returned. Notes cctalk_app_event_name() always returns a valid, non-empty, NUL-terminated C string. Example
#include <connector_sdk.h> #include <ccTalk.h> #include <cctalk_app.h> using namespace __CONNECTOR_SDK; void my_event_handler(PDG_CCTALK_APP_EVT *pEVT) { DG_CCTALK_APP_DEVICE_INFO sDeviceInfo; DG_ERROR iError; iError = cctalk_app_get_device_info(pEVT, &sDeviceInfo); if (!DG_IS_SUCCESS(iError)) { // Error handling } else { printf(Event %s from device %s (address %d) on link %d\n,
DRAFT
Page 45 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 46 of 226
Parameters pEVT
An event containing the link and address information for the device which has had the bill inserted.
Description cctalk_app_accept_bill() causes a bill/note validator to accept into its stacker a bill which it currently has in the escrow position. This function may be called in response to the customer event handler receiving an event with the event code DG_CCTALK_APP_EVT_BILL_IN_ESCROW. Errors
DGERROR_OK
The operation completed successfully. event notifiying that a bill is in the escrow position.
DRAFT
Page 47 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 48 of 226
Parameters pEVT
An event containing the link and address information for the device which has had the bill inserted.
Description cctalk_app_accept_bill() causes a bill/note validator to reject (returning it to the customer) a bill which it currently has in the escrow position. This function may be called in response to the customer event handler receiving an event with the event code DG_CCTALK_APP_EVT_BILL_IN_ESCROW. Errors
DGERROR_OK
The operation completed successfully. event notifiying that a bill is in the escrow position.
Notes None. Example Please see preceding example for cctalk_app_accept_bill(). Also dgcctalk_app_demo.cpp for more information how to use the command.
see
DRAFT
Page 49 of 226
An event containing the link and address information for the device which is to have a new note-table programmed. The location of the note table file.
Description cctalk_app_load_bill_table() causes a bill/note validator to have a new bill table programmed. When the programming is completed successfully, the device is reset and an event of type DG_CCTALK_APP_EVT_BILTABLE_LOADED is delivered. If the programming fails then an event of type DG_CCTALK_APP_EVT_BILTABLE_FAILED is delivered. Errors
DGERROR_OK
The operation completed successfully. This operation is not supported by the target device.
Notes None.
DRAFT
Page 50 of 226
An event containing the link and address information for the device which is to have a new note-table programmed. The location of the note table file.
Description cctalk_app_load_firmware() causes a device with programmable firmnware to have a new firmware programmed. When the programming is completed successfully, the device is reset and an event of type DG_CCTALK_APP_EVT_FIRMWARE_LOADED is delivered. If the programming fails then an event of type DG_CCTALK_APP_EVT_FIRMWARE_FAILED is delivered. Errors
DGERROR_OK
The operation completed successfully. This operation is not supported by the target device.
Notes None.
DRAFT
Page 51 of 226
3.2.16 CCTALK_APP_GET_MONEY_IN: RETURN HOW MUCH CURRENCY HAS BEEN ACCEPTED Definition
#include <ccTalk.h> #include <cctalk_app.h> DG_ERROR cctalk_app_get_money_in(PDG_CCTALK_APP_EVT pEVT, int *piTotal);
An event containing the link and address information for the device whose money-in count is to be received, or NULL A pointer to an integer which will have the amount of currency received place into it. This parameter may not be NULL.
Description cctalk_app_get_money_in() returns the amount of currency accepted by the device in the memory pointed to by piTotal. If pEVT is NULL, then a total for all detected devices is returned. Errors
DGERROR_OK
The operation completed successfully. If the device pointed to by pEVT is not a device which accepts currency.
DRAFT
Page 52 of 226
switch (pEVT->eEventCode) { case DG_CCTALK_APP_EVT_BILL_IN_STACKER: iError = cctalk_app_get_money_in(pEVT, &iMoneyIn); printf(Accept currency to value %d\n, pEVT->iBillAmount); if (!DG_IS_SUCCESS(iError)) { // Error handling } printf(Total accepted currency now %d\n, iMoneyIn); } }
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 53 of 226
Parameters pEVT
An event containing the link and address information for the device whose money-in count is to be received, or NULL
Description cctalk_app_clear_money_in() clear the record of currency accepted by the device. If pEVT is NULL then the account of money in for all devices is cleared. Errors
DGERROR_OK
The operation completed successfully. event notifiying that a bill is in the escrow position.
DGERROR_NOTSUPPORTED
Notes None.
DRAFT
Page 54 of 226
3.2.18 CCTALK_APP_GET_CURRENCY_REVISION: RETURN AN IDENTIFIER FOR THE CURRENT BILL TABLE Definition
#include <cctalk_app.h> DG_ERROR cctalk_app_get_currency_revision( PDG_CCTALK_APP_EVT pEVT, char *pBuffer, unsigned int uiBufferLen);
An event containing the link and address information for the device whose money-in count is to be received. A buffer into which will be placed a string identifying the currently loaded bill-table The size of the buffer pBuffer. No more than uiBufferLen characters (including a NUL-terminator) will be placed in the memory pointed to by pBuffer.
Description cctalk_app_get_currency_revision() returns a string describing the bill table currently programmed into a bill/note validator. This is string is formed as follows: request the general currency revision (ccTalk command #145) request the currency specification ID (ccTalk command #91); strip trailing spaces from the specification ID and change \ to ; suffix a / then the general currency revision onto the end of the specification ID.
The operation completed successfully. If the device pointed to by pEVT is not a device which accepts currency.
DRAFT
Page 55 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Notes None. Example
#include <connector_sdk.h> #include <ccTalk.h> #include <cctalk_app.h> using namespace __CONNECTOR_SDK; void my_event_handler(PDG_CCTALK_APP_EVT *pEVT) { DG_ERROR iError; char buf[64]; switch (pEVT->eEventCode) { case DG_CCTALK_APP_EVT_FOUND_DEVICE: iError = cctalk_app_get_currency_revision(pEVT, buf, sizeof(buf)); printf(Currency revision: %s\n, buf); } }
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 56 of 226
An event containing the link and address information for the device whose money-in count is to be received. A pointer to an integer which will have placed in it the maximum number of programmed bill types supported by the bill/note validator identified by pEVT.
Description cctalk_app_get_number_bills() returns the maximum number of bills that can be programmed into the device identified by pEVT. Note that this may be different from the number of bills defined in the bill/note table currently programmed into the target device. Errors
DGERROR_OK
The operation completed successfully. If the device pointed to by pEVT is not a device which accepts currency.
DRAFT
Page 57 of 226
Please see dgcctalk_app_demo.cpp for more information how to use the command.
DRAFT
Page 58 of 226
An event containing the link and address information for the device whose money-in count is to be received. The bill number on which information is to be returned. This is a number between 0 and MAX_BILLs (as returned by cctalk_app_get_number_bills()). A pointer to some memory into which will be placed information on the bill at position iBillNo in the bill table.
pBillInfo
Description cctalk_app_get_bill_info() returns the specific information about a chosen bill in the programmed bill table. Note that in the structure returned, the ushScalingFactor member is set to the value of the bill value from the ccTalk information returned by ccTalk command #157 multiplied by the scaling factor for the country code named in the bill (this is returned by ccTalk command #156). Errors
DGERROR_OK
DRAFT
Page 59 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual which accepts currency. Notes None. Example
#include <connector_sdk.h> #include <ccTalk.h> #include <cctalk_app.h> using namespace __CONNECTOR_SDK; void my_event_handler(PDG_CCTALK_APP_EVT *pEVT) { DG_ERROR iError; int iMaxBills, iBillNo; switch (pEVT->eEventCode) { case DG_CCTALK_APP_EVT_FOUND_DEVICE: iError = cctalk_app_get_number_bills(pEVT, &iMaxBills); for (iBillNo = 0; iBillNo < iMaxBills; iBillNo++) { DG_CCTALK_BILL_INFO sBillInfo; iError = cctalk_app_get_bill_info(pEVT, iBillNo, &sBillInfo); if (!DG_IS_SUCCESS(iError)) { // error handling... } printf(Bill #%d is country %c%c value %d, issue %c\n, sBillInfo.CountryCode[0], sBillInfo.CountryCode[1], sBillInfo.ushScalingFactor, sBillInfo.chIssueCode); } } }
Please see dgcctalk_app_demo.cpp for more information how to use the command
DRAFT
Page 60 of 226
3.3
These commands are complementary to the application layer API functions and may be used to effect additional control of the devices connected to your main-board hardware. 3.3.1
CCTALK_OPEN_LINK: OPEN LINK CONNECTION
Definition
DG_ERROR cctalk_open_link(IN char* pInitString, IN unsigned char uchHostAddress, IN DGT_CCTALK_CRC uchCRCType, OUT int *piHandle);
Parameters
pInitString
A pointer to NULL terminated string, which specifies the initialization parameters. The initialization string has the following format: <link library>: <link library init parameters> Where Link library The link library file name. Link library_init_parameters The parameters passed to the link library.
ccTalk
device
to
establish
the
The valiable defines the CRC calculation type that will be used to validate the integrity of sent and received data. The possible values are: DG_CCTALK_CRC_8_BIT and DG_CCTALK_CRC_16_BIT A pointer to int variable where the function stores a handle value to the opened link.
piHandle
Description The function establishes a link and returns a handle, which is used by other functions of the library. This is the first function that must be used in order to use any other functions provided by the library. Errors
DGERROR_NORESOURCES
DRAFT
Page 61 of 226
Notes If the physical connection has already been established by another thread then the function returns a handle but ignores the specified link library initialization parameters. This function should not be used if the ccTalk application layer has been initialized and the same port has been added using cctalk_app_add_link(). Example
#include <connector_sdk.h> #include <ccTalk.h> using namespace __CONNECTOR_SDK; DG_ERROR iResult; int iHandle; //Linux init string char chInitStr[]=rs:port=/dev/ttyS0,baudrate=9600,bytesize=8,stopbit= 1,parity=no; //Windows init string char chInitStr[]=rs:port=com1,baudrate=9600,bytesize=8,stopbit=1,pari ty=no; iResult = cctalk_open_link (chInitStr, 3, DG_CCTALK_CRC_8_BIT, &iHandle); if(DG_IS_SUCCESS(iResult)) { //Success }
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 62 of 226
3.3.2
Definition
void cctalk_close_link(IN int iHandle);
Parameters
iHandle
Description The function closes the established link connection when it is not needed anymore. Notes If the physical connection is still used by other threads then it still stays open until all the threads call the close function. Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Page 63 of 226
3.3.3
Definition
DG_ERROR cctalk_cmd_simple_poll(IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the device to poll.
Description The function is used to check if the slave device is powered up and working. The command implements header 254. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 64 of 226
3.3.4
Definition
DG_ERROR cctalk_cmd_address_poll(IN int iHandle, IN unsigned char* pAddressList, IN unsigned int uiAddressListSize, OUT unsigned int *puiDataReceived);
Parameters
iHandle pAddressList
that
was
returned
by
an address list of
Pointer to an integer variable where the function returns the number of the devices that replied to the request.
Description The function is used to determine which devices are connected to the bus by requesting that all attached devices return their address. The function implements command header 253. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 65 of 226
3.3.5
Definition
DG_ERROR cctalk_cmd_address_clash( IN int iHandle, IN unsigned char* pAddressList, IN unsigned int uiAddressListSize, OUT unsigned int *puiDataReceived);
Parameters
iHandle pAddressList
that
was
returned
by
Pointer to a buffer which will hold an address list of all the devices that replied. Pointer to an integer variable where the function returns the number of the devices that replied to the request.
Description The function is used to determine if one or more devices share the same address. The function implements command header 252. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 66 of 226
3.3.6
Definition
DG_ERROR cctalk_cmd_address_change( IN int iHandle, IN unsigned char uchDstAddress, unsigned char uchNewAddress);
Parameters
iHandle uchDstAddress uchNewAddress
A valid handle value that was returned by cctalk_open_link function. The address of the device that should execute the command. The new address value that the device should respond to.
Description The function is used to change the address of a device to the specified new value. The command implements header 251. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. The addressed device did not reply. Failed to acquire access to the stream specified by the handle. to
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 67 of 226
3.3.7
Definition
DG_ERROR cctalk_cmd_address_random( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the device that should execute the command.
Description The function is used to change the address of a device to random value. This is the escape route when one or more devices share the same address. The command implements header 250. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 68 of 226
3.3.8
Definition
DG_ERROR cctalk_req_polling_priority( IN int iHandle, IN unsigned char uchDstAddress, OUT PDG_POLL_PRIORITY pPollPriority)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the device to poll. to DG_POLL_PRIORITY structure where the polling information is returned. The pPollPriority->Units member specifies the polling units. The following values are permitted: DG_CCTALK_PP_UNSPECIFIED DG_CCTALK_PP_MS DG_CCTALK_PP_10MS DG_CCTALK_PP_SECONDS DG_CCTALK_PP_MINUTES DG_CCTALK_PP_HOURS DG_CCTALK_PP_DAYS DG_CCTALK_PP_WEEKS DG_CCTALK_PP_MONTHS DG_CCTALK_PP_YEARS
pPollingPriority Pointer
Description The function reads the recommended polling interval for buffered credit information. Polling a device at an interval longer than this may result in lost credits. If pPollPriority->Units = DG_CCTALK_PP_UNSPECIFIED and pPollPriority>uchValue = 0 then refer to the product manual for polling information If pPollPriority->Units = DG_CCTALK_PP_UNSPECIFIED and pPollPriority>uchValue = 255 then the device uses a hardware REQUEST POLL line The implemented command header is 249 Errors
DGERROR_NORESOURCES
The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 70 of 226
3.3.9
Definition
DG_ERROR cctalk_req_status(IN int iHandle, IN unsigned char uchDstAddress, OUT DGT_CCTALK_CA_STATUS *pAcceptorStatus)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device . function returns the status of a coin acceptor. The following are valid: DG_CCTALK_CA_OK DG_CCTALK_CA_DECK_OPEN DG_CCTALK_CA_COS_ACTIVATED
Description The function reports the status of a coin acceptor. The implemented command header is 248 Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 71 of 226
3.3.10
Definition
DG_ERROR cctalk_req_variable_set(IN int iHandle, IN unsigned char uchDstAddress, IN char* pBuffer, IN unsigned int uiBufferLen, OUT unsigned int *puiDataLen)
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read a set of variables from the slave device. The number of variables is determined by the hardware manufacture. The command implements header 247. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 72 of 226
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read the unique device's manufacture name. The command implements header 246. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 73 of 226
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read the standard equipment category identification string. The command implements header 245. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 74 of 226
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read the product code. The command implements header 244. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 75 of 226
Parameters
iHandle uchDstAddress pCDBVersion
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to unsigned char variable where the function returns the database version. The valid values are 0 to 255.
Description The function retrieves a database number from 1 to 255 which may be used for remote coin programming. A database number of 0 indicates remote coin programming is not possible. The implemented command header is 243. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 76 of 226
Parameters
iHandle uchDstAddress pSerialNumber
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. A pointer to DG_SERIAL structure where the serial number is returned.
Description The function is used to read the devices serial number. The command implements header 242. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 77 of 226
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read the slave devices software revision. The command implements header 241. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 78 of 226
Parameters
iHandle uchDstAddress uchSlenoidMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The solenoid bit mask. The mask can be combined from the following valid flag values: DG_CCTALK_FL_GATE_SOLENOID DG_CCTALK_FL_SORTER_SOLENOID1 DG_CCTALK_FL_SORTER_SOLENOID2 DG_CCTALK_FL_SORTER_SOLENOID3
Description The function send command to a coin acceptor which in responds pulses the solenoids for a set time. The bit mask indicates which solenoids to operate. The command implements header 240. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 79 of 226
Parameters
iHandle uchDstAddress uchOLinesMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The output lines bit mask. 0-no action, 1-pulse.
Description The function send command to a coin acceptor which in responds pulses the output lines for a set time. The bit mask indicates which lines to pulse. The length of the pulses is product specific. The command implements header 238. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 80 of 226
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Address of buffer where the function returns the recevied data. The length of the provided buffer. Pointer to the variable where the number of read bytes is returned.
Description The command is implemented on slave devices which have an input port. This command requests various input data from a slave device and is an excellent debugging tool. It can be used to check the operation of switches, push buttons, connector signals, processor input lines etc. Refer to the product manual for more details. The command implements header 237. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
Page 81 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 82 of 226
Parameters
iHandle uchDstAddress puchBitMask
A valid handle value that was returned by cctalk_open_link function. The address of the device to poll. A pointer to a variable where an opto mask is returned.
Description The function is used to check the state of various opto devices in the slave device. The command implements header 236. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
Page 83 of 226
Parameters
iHandle uchDstAddress uchOLinesMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The output lines bit mask. 0-no action, 1-pulse.
Description Implemented on slave devices which have an output port. Various output lines are latched. The bit mask indicates which lines to latch. Polarities and bit mask interpretation will be detailed in the product manual. The command implements header 233. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 84 of 226
Parameters
iHandle uchDstAddress pFaultCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to DG_FAULT_CODE variable where the fault code is returned.
Description This command instructs the peripheral device to perform a self-check, i.e. a full diagnostic test without user intervention. The actual level of testing is decided by the slave rather than the host and a fault code is returned. Some slave devices support an additional byte of information for certain fault codes. Where more than one fault exists on a product, faults will be reported in priority order. Once one fault is fixed, the next fault will be reported. The time to execute this command should be made clear in the product manual. The command implements header 232. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 85 of 226
Parameters
iHandle uchDstAddress ushEnableMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable which contains the enable coins/bills mask. You can use DG_CCTALK_FL_COIN(CoinNmb) macro to specify which coin/bill to enable. For example: DG_CCTALK_FL_COIN(0) enable coin/bill 1, DG_CCTALK_FL_COIN(1) + DG_CCTALK_FL_COIN(10) enable coins/bills 2 and 11. The maximum CoinNmb value is 15.
Description The function sends an individual inhibit pattern to a coin acceptor or bill validator. With a 2 byte inhibit mask, up to 16 coins or bills can be inhibited or enabled. 0 = coin / bill disabled ( inhibited )
1 = coin / bill enabled ( not inhibited ) The product manual should make clear whether these changes are permanent ( stored in non- volatile memory ) or temporary ( stored in RAM ). The command implements header 231. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. Failed to acquire access to the stream specified by the handle. The addressed device did not reply. DRAFT Page 86 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 87 of 226
Parameters
iHandle uchDstAddress pEnableMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to DG_CCTALK_COPY_BUFFER structure which holds information about user specified buffer. The buffer contain required inhibit infomraion and number of bytes in the buffer.
Description The function is the same as cctalk_cmd_modify_inhibit_status but some devices can accept more than two bytes data. Therefore structure DG_CCTALK_COPY_BUFFER is used to transmit variable sized information. The structure is defined as follows:
typedef struct _DG_CCTALK_COPY_BUFFER { void *pBufferPtr; unsigned int uiBufferSize; unsigned int uiDataCopied; } DG_CCTALK_COPY_BUFFER, *PDG_CCTALK_COPY_BUFFER;
where
pBufferPtr uiBufferSize uiDataCopied
Pointer to user allocated buffer which holds inhibit masks. Size of the user allocated buffer. Unused.
The operation completed successfully. Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 89 of 226
Parameters
iHandle uchDstAddress pEnableMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to unsigned short variable where the coins/bills inhibit status mask is returned.
Description The function requests an individual inhibit pattern from a coin acceptor or bill validator. Please see cctalk_cmd_modify_inhibit_status for more information. The function implements header command 230. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 90 of 226
Parameters
iHandle uchDstAddress pEnableMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to DG_CCTALK_COPY_BUFFER structure which holds information about user specified buffer. When the function returns the variable also contains the number of copied bytes.
Description The function is the same as cctalk_req_inhibit_status but some devices return more than two bytes data. Therefore structure DG_CCTALK_COPY_BUFFER was introduced to receive variable size information. The structure is defined as follows:
typedef struct _DG_CCTALK_COPY_BUFFER { void *pBufferPtr; unsigned int uiBufferSize; unsigned int uiDataCopied; } DG_CCTALK_COPY_BUFFER, *PDG_CCTALK_COPY_BUFFER;
where
pBufferPtr uiBufferSize uiDataCopied
Pointer to user allocated buffer. Size of the user allocated buffer. Number of bytes that have been copied into the buffer.
The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 92 of 226
Parameters
iHandle uchDstAddress pEvents
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to DG_CREDIT_EVENT structure where the function returns credit and error codes events information.
Description The function returns a past history of event codes for a coin acceptor in a small data buffer. This allows a host device to poll a coin acceptor at a rate lower than that of coin insertion and still not miss any credits or other events.validator. The DG_CREDIT_EVENT structure has the following definition:
typedef struct _DG_CREDIT_EVENT { unsigned int uiEventCnt; struct _DG_EVENT { DGT_EVENT_TYPE Type; union _DG_EVENT_ENTRY { struct _DG_CREDIT_ENTRY { unsigned short ushCoin; unsigned short ushSorterPath; } Credit; DGT_CCTALK_EVT_ERROR_CODE ErrorCode; } Event; } Events[DG_CCTALK_EVENTLIST_SIZE]; } DG_CREDIT_EVENT, *PDG_CREDIT_EVENT;
If the Type member of the _DG_EVENT structure is set to DG_CCTALK_EVT_CREDIT then the relevant information should be accessed using Credit member of the _DG_EVENT_ENTRY union. If the Type member is set to DG_CCTALK_EVT_ERROR then the ErrorCode member of the _DG_EVENT_ENTRY union contains the error code. The function implements header command 229.
DRAFT
Page 93 of 226
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 94 of 226
Parameters
iHandle uchDstAddress InhibitStatus
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable specifies the new inhibit status. The value DGT_CCTALK_INHIBIT_ENABLED enables the inhibit status where no coins or bills are accepted. The value DGT_CCTALK_INHIBIT_DISABLED returns the device into normal mode of operation.
Description The function changes the master inhibit status in the slave device. In a coin acceptor, if the master inhibit is active then no coins can be accepted. Likewise for a bill validator. The product manual sho uld make clear whether this change is permanent ( stored in non-volatile memory ) or temporary ( stored in RAM ). The function implements header command 228. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 95 of 226
Parameters
iHandle uchDstAddress pInhibitStatus
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to a variable where the inhibit status is returned. The value DG_CCTALK_INHIBIT_ENABLED specifies that the inhibit status is enabled - no coins or bills are accepted. The value DG_CCTALK_INHIBIT_DISABLED specifies that the device is functioning in normal mode of operation.
Description The function requests the master inhibit status in the slave device. The function implements header command 227. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 96 of 226
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. coins/bills put through the device is returned..
Description This command returns the total number of coins / bills put through a device. The function implements header command 226. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 97 of 226
Parameters
iHandle uchDstAddress puiAcceptCount
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to a variable where the total number of coins/bills accepted by the device is returned..
Description This command returns the total number of coins / bills accepted by a device. The function implements header command 225. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Page 98 of 226
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Bit 0 - Sorter Path 1 ..................... Bit 7 - Sorter Path 8 1 - sorter override to a different or default path. 0 - no action, normal sorting Use macro DG_CCTALK_FL_SORTER(PathNmb) to specify which sorter path needs overriding. You can also override several paths using | or + operators: DG_CCTALK_FL_SORTER(0) + DG_CCTALK_FL_SORTER(4).
Description This command allows the sorter override status to be set in a coin acceptor. Each bit represents a sorter path for the accepted coin. A bit set to 1 overrides that sorter path to another one ( possibly the default sorter path ). The product manual should make clear whether this change is permanent (stored in nonvolatile memory ) or temporary ( stored in RAM ). The command implements header 222. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully.
DRAFT
Page 99 of 226
The provided buffer is too small accommodate all of the received data.
to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. is returned. If a bit in the bit mask is set it means that the sorter path has an active override.
Description The command returns the sorter override status in a coin acceptor. Each bit represents a sorter path for the accepted coin. A zero means tha t the sorter path has an active override. Refer to the cctalk_cmd_modify_sorter_status command for more details. The command implements header 221. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pPinNumber
that
was
returned
by
The address of the slave device. A pointer to the DG_PIN_NUMBER structure, which contains the new PIN number.
Description Certain commands can be PIN protected. The function allows to change the existing PIN number to a new one. This command is itself PIN protected so the existing PIN number should have been entered before this function is called. The command implements header 219. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pPinNumber
that
was
returned
by
The address of the slave device. A pointer to the DG_PIN_NUMBER structure, which contains the PIN number.
Description Certain commands can be PIN protected. The function allows to enter a PIN number so the PIN protected commands can be successfully executed. This has to be done after each power-up or reset. The command implements header 218. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress shHopperNumber
A valid handle value that was returned by cctalk_open_link function. The address of the device to poll. A hopper number if multiple hoppers exist. Set this value to 1 if only one hopper is connected.
Description The function is used to read the high/low level sensors in a payout system. The command implements header 217. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
Parameters
iHandle uchDstAddress pStorage
A valid handle value that was returned by cctalk_open_link function. The address of the device to poll. A pointer to DG_STORAGE_INFO structure where the memory information is stored. The MemoryType member of the structure specifies the type of storage provided by the slave device: DG_CCTALK_MEM_VOL_RESET Volitile memory that loses data on reset. DG_CCTALK_MEM_VOL_POWER Volitile memory that loses data on power down. DG_CCTALK_MEM_PERM_LIMITED Permanent memory but of limited use. DG_CCTALK_MEM_PERM_UNLIMITED memory. Permanent
Description Some slave devices allow host data to be stored for whatever reason. The function is used to determine whether this service is provided. The command implements header 216. Note that this function corrects the block count to be 256 when the raw ccTalk data is zero, as per the special case notes in the ccTalk Generic Specification, section 3.40. Doc. ref. 200-338_0.1 DRAFT Page 105 of 226
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
Parameters
iHandle uchDstAddress uchBlockNumber pData uiDataLen puiDataRead
A valid handle value cctalk_open_link function. The block to write the data to.
that
was
returned
by
The address of the slave device. Pointer to the buffer where the data is read to. The size of the provided buffer. Pointer to a variable where the number of read bytes is copied into.
Description Some slave devices allow host data to be stored for whatever reason. This function allows to read the data from a slave device. The function read data in blocks and returns the number of read bytes. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchBlockNumber pData uiDataLen
A valid handle value cctalk_open_link function. The block to write the data to.
that
was
returned
by
The address of the slave device. Pointer to the buffer which contains the data. The number of byte to write from the specified buffer.
Description Some slave devices allow host data to be stored for whatever reason. This function allows to write the data into a slave device. The command implements header 214. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress puchOFlags
that
was
returned
by
The address of the slave device. Pointer to a variable where the function stores the option flags.
Description The command reads option flags ( single bit control variables ) rom a slave device. If the slave device is a bill validator then the following macros can be used to test check the supported features: DG_CCTALK_FL_OP_STACKER DG_CCTALK_FL_OP_ESCROW DG_CCTALK_FL_OP_ACCEPT_COUNTERS DG_CCTALK_FL_OP_ERROR_COUNTERS DG_CCTALK_FL_OP_BILL_TEACH DG_CCTALK_FL_OP_BILL_SECURITY - Stacker - Escrow - Individual bill accept counters. - Individual error counters. - Bill teach facility. - Bill security tuning.
DG_CCTALK_FL_OP_BILL_PROGRAMMING - Remote bill programming. If the slave device is a coin acceptore then following macro can be used to test the options: DG_CCTALK_FL_OP_CVF - Credit Code Format is in Coin Value format.
Please refer to ccTalk Generic specification for further information. The command implements header 213. Errors
DGERROR_NORESOURCES
DRAFT
The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCreditCode pushPosMask
that
was
returned
by
The address of the slave device. The value returned by the Read buffered credit or error codes command. Address of a variable where the coin position mask is returned.
Description This command can be used in coin acceptors to locate the inhibit position of a given coin based on its credit code. The inhibit position ties up with the 'Modify inhibit status' command for inhibiting individual coins. The command implements header 212. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCoinPos pSorterPaths
that
was
returned
by
The address of the slave device. The variable specifies the coin position. The valid values are 1 to 16. Pointer to PDG_CCTALK_SORTER_PATHS structure which specifies the sorter path(s). PDG_CCTALK_SORTER_PATHS.uchPathsLen - specifies the number of paths that should be transmitted to the slave device. The valid values are 1 and 4. PDG_CCTALK_SORTER_PATHS.Paths[4] - The array where the sorter paths. The valid values for each element are 1 to 8.
Description This command modifies the sorter path for each coin position in a coin acceptor. Some coin acceptors support multiple sorter paths (override paths) so the DG_CCTALK_SORTER_PATHS.uchPathsLen member of the structure should specify the number of the paths (1 or 4). The function implements header command 210. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. DRAFT to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCoinPos pSorterPaths
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Specifies the coin position . The valid values are from 1 to 16. Pointer to a DG_CCTALK_SORTER_PATHS type variable where the sorter paths are returned. The DG_CCTALK_SORTER_PATHS.uchPathsLen specifies the number of valid values in DG_CCTALK_SORTER_PATHS.Paths array.
Description The function requests coin sorter paths from a coin acceptor. The function implements header command 209. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchPosition uchOrientation
that
was
returned
by
The address of the slave device. The coin position parameters. The valid values are 1 to 16. The orientation parameter. The valid values are 1 to 4. Some devices do not support this parameter in which case it should be set to 0.
Description The command puts the device into teach mode. Teach is a mechanism whereby new coins or bills can be learnt by entering a representative sample. On existing Money Controls products this is referred to as Teach-and-run. Once in teach mode the device should be polled with the Request teach status command to see what is happening. The function implements header command 202. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command. Doc. ref. 200-338_0.1 DRAFT Page 116 of 226
3.3.45
Definition
DG_ERROR cctalk_req_teach_status(IN int iHandle, IN unsigned char uchDstAddress, IN DGT_CCTALK_REQ_TSTAT TRequest, OUT PDG_TEACH_STATUS pTStatus)
Parameters
iHandle uchDstAddress TRequest pTStatus
that
was
returned
by
The address of the slave device. DGT_CCTALK_REQ_TSTAT type variable which specifies the type of teach status request. Pointer to DG_TEACH_STATUS type variable where the function returns the current teach status and coin/bill counter.
Description The command is used to monitor the progress of teach mode. Only when a teach completed status message is received can the operation be deemed successful. The actual teach mechanism is under the full control of the slave device. It decides when enough coins or bills have been entered. The function implements header command 201. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command. Doc. ref. 200-338_0.1 DRAFT Page 117 of 226
Parameters
iHandle uchDstAddress
that
was
returned
by
Description This command transfers volatile configuration information for a device from RAM into EEPROM. The information for a coin acceptor could possibly include a) inhibit information b) sorter override information c) sorter paths Refer to the product manual for more details. The function implements header command 199. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress
that
was
returned
by
Description This command transfers volatile counter information from RAM into EEPROM. The information for a coin acceptor could include a) coin insertion counter b) coin accept counter c) coin reject counter d) error or alarm counter Refer to the product manual for more details. The function implements header command 198. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pulSum
that
was
returned
by
The address of the slave device. Pointer to a variable where the calculated ROM checksum is returned.
Description The function sends a request to a slave device to calculate its ROM checksum and returns the result. The function implements header command 197. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pDate
that
was
returned
by
The address of the slave device. Pointer to DG_CCTALK_DATE structure where the date is returned.
Description The function returns the creation date which is also known as the manufacturing date or factory setup date. The year is always stored relative to the PRODUCT_BASE_YEAR which will either be in the product manual or available using the Request base year command. The creation date is a maximum of 31 years after the base year. The function implements header command 196. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pDate
that
was
returned
by
The address of the slave device. Pointer to DG_CCTALK_DATE structure where the date is returned.
Description The function returns the last modification date of the product. It is usually changed by remote programming toolkits or PC-based support software. The function implements header command 195. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCounter
that
was
returned
by
The address of the slave device. Pointer to a variable where the reject counter value is returned.
Description The function returns the total number of reject coins / bills put through a device. The function implements header command 194. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCounter
that
was
returned
by
The address of the slave device. Pointer to a variable where the reject counter value is returned.
Description The function returns the total number of fraud coins / bills put through a device. The function implements header command 193. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read devices product build code. The command implements header 192. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information on how to use the command.
DRAFT
Parameters
iHandle uchDstAddress
that
was
returned
by
puchCoinsRemaining The default sorter path position. The valid values are 1 to
Description This command allows the default sorter path on a coin acceptor to be changed. If there is an active override on the current coin sorter path then it will be routed to the default path. The product manual should make clear whether this change is permanent ( stored in non-volatile memory ) or temporary ( stored in RAM ). The function implements header command 189. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pDefSorter
that
was
returned
by
The address of the slave device. Pointer to a variable where the default sorter path value is returned.
Description This command reads the default sorter path on a coin acceptor. See the Modify default sorter path command for more details. The function implements header command 188. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCoinPos pCoinDesc
that
was
returned
by
The address of the slave device. Specifies the coin position to modify. Address of the coin DG_CCTALK_COIN_DESC. description structure
Description Some coin acceptors can store an identification string alongside the normal validation parameters for each coin. Refer to the product manual for details. The command implements header 185. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCoinPos pCoinDesc
that
was
returned
by
The address of the slave device. Address of the coin description structure DG_CCTALK_COIN_DESC where the coin information is returned.
Description This command returns the coin identification string. The command implements header 184. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pDataBuffer uiDataBufferLen
that
was
returned
by
The address of the slave device. The buffer address that contains the data to be uploaded to a coin acceptor. The size of the data buffer.
Description This command is used for the remote programming of coins or tokens. The command implements header 183. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataCopied
that
was
returned
by
The address of the slave device. Pointer to the buffer where the received data is stored. The size of the provided buffer. Pointer to a variable where the actual number of the recevied data is stored. If the function returns DGERROR_BUFFER_TOO_SMALL then the variable returns the necessary size of the buffer.
Description This command is used to support the remote coin programming operation. Please refer to manufacture's manual for further details. The command implements header 182. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command. Doc. ref. 200-338_0.1 DRAFT Page 131 of 226
DRAFT
Definition
DG_ERROR cctalk_cmd_modify_security ( IN int iHandle, IN unsigned char uchDstAddress, IN unsigned char uchCoinPos, IN unsigned char uchSecurity)
Parameters
iHandle uchDstAddress uchCoinPos uchSecurity
that
was
returned
by
The address of the slave device. Coin position to modify the security settings of. The valid value are 1-16. Security settings for the specified coin position.
Description This command allows a validators performance to be finely tuned. On all known devices there is a trade-off between fraud rejection and true acceptance. The product manual should make clear whether this change is permanent ( stored in non-volatile memory ) or temporary ( stored in RAM ). The command implements header 181. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchCoinPos puchSecurity
that
was
returned
by
The address of the slave device. The variable specifies the coin position the security settings should be returned for. The valid values are 1-16. Pointer to a variable the security setting is stored.
Description The function is used to read the security settings for the specified coin position. The command implements header 180. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchBankNmb
that
was
returned
by
The address of the slave device. The variable specifies the coin/bill bank.
Description Some devices can support multiple banks of coins / bills subject to the condition of only a single bank being enabled ( active ) at any one time. This command allows the host controller to switch between banks. Assuming a typical device operates with 16 coins or bills, this command expands the potential capability to 16 x 256 = 4,096 coins or bills, though not all can be accepted concurrently. Coins or bills within a bank can be controlled with the Modify inhibit status command. The function implements header command 179. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress puchBankNmb
that
was
returned
by
The address of the slave device. Pointer to a variable where active coin/bill bank number is returned.
Description Some devices can support multiple banks of coins / bills subject to the condition of only a single bank being enabled ( active ) at any one time. This command allows the host controller to request the currently active bank number. The function implements header command 178. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress puiAlarmCount
that
was
returned
by
The address of the slave device. Pointer to a variable where the alarm count is returned.
Description This command returns the number of alarm events since the last request was sent ( i.e. it is cleared on reading ). It is only used on products which support an alarm output line. The function implements header command 176. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pchReading
that
was
returned
by
The address of the slave device. Pointer to a variable where the thermistor value is returned.
Description Some products use a thermistor to provide an approximate method of determining the ambient temperature. This command returns the raw thermistor reading as a byte. This command is no longer restricted to thermistor temperature measurement more accurate methods are commonly available. The format of the return data is now specified as degrees Celsius in 2s complement format. This gives a range of -128C to +127C. The function implements header command 173. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress puiBaseYear
that
was
returned
by
The address of the slave device. Pointer to an int variable where the base year value is returned.
Description The function returns the product base year ( see PRODUCT_BASE_YEAR in Request creation date and Request last modification date commands ) The function implements header command 170. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress
that
was
returned
by
Description This function immediately halts the payout sequence and reports back the number of coins which failed to be paid out. The command implements header 172. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pBuffer uiBufferLen puiDataLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer where the received data is stored. The size of the provided buffer in bytes. A pointer to a variable where the number of received bytes is returned.
Description The function is used to read the coin name that the device can pay out. The command implements header 171. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pModeMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to a variable where the function returns the address mode mask.
Description The function returns the ccTalk addressing mode to help with automatic reconfiguration of ccTalk peripherals. Use the following macros to test the bit mask:
DG_CCTALK_FL_AM_ROM DG_CCTALK_FL_AM _RAM DG_CCTALK_FL_AM_EEPROM DG_CCTALK_FL_AM_INTERFACE DG_CCTALK_FL_AM_PCB DG_CCTALK_FL_AM_SWITCH DG_CCTALK_FL_AM_CMD_VOLITILE
The address is stored in ROM. The address is stored in RAM. The address is stored in EEPROM or NV memory The address is selected via interface connector. The address is selected via PCB links. The address is selected via a switch. The address may be changed with serial commands (volatile). commands (non-volatile).
Failed to allocate memory to complete the operation. The operation completed successfully. DRAFT Page 142 of 226
The provided buffer is too small accommodate all of the received data.
to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. number of dispensed coins.
Description The function returns the number of coins dispensed by the hopper. The command implements header 168. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchNumberOfCoins pSecurityCode
that
was
returned
by
The address of the slave device. The number of coins to dispense. Pointer to a buffer which contains the security code. Pointer to a variable where the event counter is returned. The variable can be set to -1 in one of the following conditions: If a non ACK or NAK message was received. The slave device did not return the event counter value although the command completed successfully.
Description The function allows to dispense hopper coins securely. The variable data in the pSecurityCode buffer represents special security codes, which have to be correct for a coin payout to be successful. The command implements header 167. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small to
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual accommodate all of the received data.
DGERROR_LINK_CONFIG DGERROR_TIMEOUT
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pStatus
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to DG_HOPPER_STATUS structure where the function returns the hoppers status.
Description The function returns the current hoppers status. The command implements header 166. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pBuffer uiBufferLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer which contains new variables values. The length of the buffer.
Description The function modifies variable data on the slave device. The variable set is product dependent and therefore you need to consult the slave device manual. The command implements header 165. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress EnableCode
that
was
returned
by
The address of the slave device. The variable contains the hopper enable code. DG_CCTALK_PAYOUTS_DISABLE Enable payouts. DG_CCTALK_PAYOUTS_ENABLE Disable payouts.
Description This function must be used to enable the hopper before making any payouts. The command implements header 164. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pStatus
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to DG_HOPPER_TEST_STATUS structure where the function returns various operating and error flags.
Description The function reports back various operating and error flags from the hopper and is the equivalent of the Perform self-checkcommand in coin/bill acceptors . The DG_HOPPER_TEST_STATUS.uchRegister1 member is a bit mask variable. Use the following macros to test the status condition:
DG_CCTALK_FL1_CURRENT_EXCEEDED DG_CCTALK_FL1_PAYOUT_TIMEOUT DG_CCTALK_FL1_MOTOR_REVERSED DG_CCTALK_FL1_FRAUD_PATH_BLOCKED DG_CCTALK_FL1_FRAUD_SHORT_CIRCUIT
Absolute exceeded.
maximum
current
Payout timeout occurred. Motor reversed during payout to clear a jam. Opto fraud attempt, blocked during idle. Opto fraud attempt, circuit during idle. blocked during payout. Power-up detected. Payout disabled. last path short-
permanently
The DG_HOPPER_TEST_STATUS.uchRegister2 member is also a bit mask variable. The following macros can be used to test the bit pattern: Doc. ref. 200-338_0.1 DRAFT Page 150 of 226
fraud attempt, short circuit during payout. Single coin mode. PIN number mechanism.
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCompoundRegs
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to compound DG_CCTALK_REGISTERS type structure which contains inhibit and status override settings.
Description For coin acceptors this command a) sets inhibits and overrides in one operation ( see also the Modify inhibit status command and the Modify sorter override status command ) b) sets both a current value and a next coin value The benefit of using this command is that it allows precise coin-by-coin control of the coin acceptor and provides a means of tackling the inherent latency in serial operation. If the next coin is always disabled, the validator will only accept one coin at a time. After each credit ( strictly speaking an attempted accept sequence ) the host software can request another coin and thus control the overall accept rate. If the next coin overrides are always active, the validator will only route one coin at a time to a payout tube - all other coins will go to the cashbox. The host software can thus maintain a precise fill level in any tube. The command implements header 162. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
DRAFT
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pRNGBuffer uiRNGBufferLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The buffer which contains RND seed number. The length of the buffer.
Description The function pumps the slaves random number generator with a set of random numbers and is part of the hopper dispense encryption algorithm. The command implements header 161. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pKeyBuffer uiKeyBufferLen puiKeyLen
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to a buffer where the function will store a cipher key. The size of the provided buffer. The size of the returned cipher key in bytes.
Description The function requests a cipher key from the slave device and is part of the hopper dispense encryption algorithm. The command implements header 160. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pBillEvents
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to DG_CCTALK_BILL_EVENTS structure where the history of bill events is returned.
Description The function requests a history of bill events in a similar way of that of a coin acceptor. The DG_CCTALK_BILL_EVENTS structure is defined as follows:
typedef struct _DG_CCTALK_BILL_EVENTS { unsigned int uiEventCounter; DG_CCTALK_BILL_EVENT EventList[DG_CCTALK_EVENTLIST_SIZE]; } DG_CCTALK_BILL_EVENTS, *PDG_CCTALK_BILL_EVENTS;
where
uiEventCounter EventList
Is a counter which is incremented when a new event is registered. Is an array which holds the events returned from an acceptor.
where
EvtCode
DRAFT
If EvtCode is set to DGT_CCTALK_BEVT_C_STACKED or DGT_CCTALK_BEVT_P_ESCROWED then the variable specifies the bill type that was either stacked or is in the escrow position. In any other case it is set to 0.
The code which is returned in EvtCode variable has event code type embedded into it. The possible event types are:
DGT_CCTALK_EVT_CREDIT
Set for an event, which implies that a credit can be issued (a note has been validated and stacked). Set for an event, which implies that a credit is pending (a note is in the escrow position). Set for an event, which belongs to the STATUS group. It is an informative event. Set for an event, which belong to the REJECT group. It implies that the a note has been rejected for some reson. Set for an event, which belong to the ERROR group. It implies that an error occurred and needs attention. Set for an event, which belong to the FRAUD group. It implies that the device detected a fraud attempt.
DGT_CCTALK_EVT_PENDING_CREDIT
DGT_CCTALK_EVT_STATUS DGT_CCTALK_EVT_REJECT
DGT_CCTALK_EVT_ERROR
DGT_CCTALK_EVT_FRAUD
In order to extract event type from the full event code use the macro called GET_BILL_EVENT_TYPE. If you only need the event code value on its own then use GET_BILL_EVENT_CODE macro. The command implements header 159. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified DRAFT Page 157 of 226
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchBillType pBillInfo
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable specifies which bill type information is required The valid values are from 1 to 16. Pointer to structure DG_CCTALK_BILL_INFO where bill information is returned. This includes country code, country scaling factor and bill issue code.
Description The function requests idenitification string alongside the normal validation parameters for each bill specified by bill type variable. Type DG_CCTALK_BILL_INFO has the following definition:
typedef struct _DG_CCTALK_BILL_INFO { char CountryCode[2]; unsigned short ushScalingFactor; char chIssueCode; } DG_CCTALK_BILL_INFO, *PDG_CCTALK_BILL_INFO;
where
CountryCode
An array 2 bytes long which contains 2 letter country code. See Appendix 10 of ccTalk specification for the valid country codes. Issue code. Starts at A and progresses B, C, D, E
DRAFT
The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCountryCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a 2 bytes buffer where country code is specified associated with the returned information. See Appendix 10 of ccTalk specification for the valid country codes. returned.
Description The function requests the scaling factor and decimal places for the standard country code provided. All the information is returned in the structure as described below:
typedef struct _DG_CCTALK_COUNTRY_SCALING { unsigned short ushScalingFactor; unsigned short ushDecimalPlaces; } DG_CCTALK_COUNTRY_SCALING, *PDG_CCTALK_COUNTRY_SCALING;
where
ushScalingFactor Value of scaling factor. ushDecimalPlaces Value of decimal places.
If ushScalingFactor and ushDecimalPlaces are set to 0 then the specified country code is not supported abd the function returns DGERROR_INVALID_DATA error code. The command implements header 156.
DRAFT
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
DGERROR_INVALID_PARAMETER One of the specified parameters is invalid. DGERROR_BUFFER_TOO_SMALL DGERROR_LINK_CONFIG DGERROR_TIMEOUT DGERROR_INVALID_DATA
Failed to acquire access to the stream specified by the handle. The addressed device did not reply. The specified country code is invalid and is not supported by the device.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCountryCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a 2 bytes buffer where country code is specified associated with the returned information. See Appendix 10 of ccTalk specification for the valid country codes. Pointer to a variable where bill position mask is returned.
pPosMask
Description The function is used to locate the inhibit mask of a given currency based on its country code. The inhibit mask ties up with the 'Modify inhibit status' command for inhibiting individual bills. If this data is used directly as the new inhibit mask then the currency selected will be enabled and all other currencies inhibited. The command implements header 155. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCountryCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a 2 bytes buffer where country code is specified associated with the returned information. See Appendix 10 of ccTalk specification for the valid country codes. Pointer to DG_CCTALK_COPY_BUFFER structure which holds information about user specified buffer. When the function returns the variable also contains the number of copied bytes.
pDataBuffer
Description The function is the same as cctalk_req_bill_position but some devices return more than two bytes of bill positioning information. Therefore structure DG_CCTALK_COPY_BUFFER was introduced to receive variable size information. The structure is defined as follows:
typedef struct _DG_CCTALK_COPY_BUFFER { void *pBufferPtr; unsigned int uiBufferSize; unsigned int uiDataCopied; } DG_CCTALK_COPY_BUFFER, *PDG_CCTALK_COPY_BUFFER;
where
pBufferPtr uiBufferSize uiDataCopied
Pointer to user allocated buffer. Size of the user allocated buffer. Number of bytes that have been copied into the buffer.
DRAFT
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress RouteCmd pReplyCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable specifies bill routing command. Pointer to a variable where an error code is returned if the device could not execute the specified command.
Description The function allows to control routing of a bill held in escrow position. The variable RouteCmd can have the following values:
DGT_CCTALK_BR_RETURN DGT_CCTALK_BR_STACK
Return the bill. Forward the bill from escrow into the stack. and extend the timeout period.
When the function returns, the pReplyCode variable contains an error code reply from a device. ccTalk library defines the following enums in accordance with ccTalk specification:
DGT_CCTALK_BRE_OK
The device returned 0 error code or ACK packet. Leave the bill in the escrow position extend the timeout period. and
It has to be noted that pReplyCode can be set to any value specified by a manufacturer. The command implements header 154.
DRAFT
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchModeMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable specifies the mask which enables or disables various features of a device..
Description The command is used to control various product features such as enabling or disabling stacker or escrow. Please consult manufacture's manual for more information. The command implements header 153. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress puchModeMask
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a variable where bill operating mode mask is returned.
Description The command is used to request enabled/disabled various product features mask. Please consult manufacture's manual for more information. The command implements header 152. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchLampNmb TestMode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Specifies lamp number to test. Variable of type DGT_CCTALK_LAMP_TEST, specifies the lamp control mode. which
Description The command is used as a diagnostic tool for products that support lamps. On bill validators, front-panel lamps are often used to guide the user on the note insertion. The command implements header 151. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchBillType puiBillCounter
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Variable, which specifies bill type - a value between 1 and 64. Pointer to a variable where pointer to accept counter is returned.
Description Some bill validators support the individual counting of different bill types. This command returns the number of bills accepted of a given type. The type is that reported by the Read buffered bill events command. The command implements header 150. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uchErrorType
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Variable, which specifies error type for which to return information for.
Description The command is used to request individual error types counters and returns the number. Please consult manufacture's manual for more information. The command implements header 149. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pVoltages
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a structure DG_CCTALK_COPY_BUFFER where raw information is returned. The pBufferPtr member of the structure should point to a user allocated buffer. uiBufferSize should be set to the size of that buffer. When the function returns the uiDataCopied member is set to the number of bytes received from the device.
Description The command returns a series of scaled voltages for a device using optos (e.g. a bill validator) rather than the blocked / clear indication, which would be returned by the 'Read opto states' command. See manufactures manual about the format the data is returned in. The command implements header 148. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pReplyCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a variable where an error code is returned if the device could not execute the specified command.
Description The function sends a command, which executes 1 cycle of the stacker on a bill validator for diagnostic purposes. After completion one of the following error codes could be returned:
typedef enum _DGT_CCTALK_STACKER_ERROR { DGT_CCTALK_SE_OK DGT_CCTALK_SE_FAULT DGT_CCTALK_SE_NOT_FITTED, DGT_CCTALK_SE_INVALID, } DGT_CCTALK_STACKER_ERROR;
= 0, = 254,
A device can also return other codes which have not been defined. Please see manufactures manual for more information. The command implements header 147. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. DRAFT Page 174 of 226
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress uiMotorNmb
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable is a number from 1 to 8, which specifies which motor to operate. Consult the device manual for more information.. The variable specifies the direction the motor should be running: forward (DGT_CCTALK_DIR_FORWARD) or backword (DGT_CCTALK_DIR_BACKWORD). The variable specifies motor speed. 0 specifies default speed. 1 to 255 - relative speed. 1 is slowest and 255 is the highest.
Direction
uchSpeed
Description The function sends the command which operates bi-directional motors. The command implements header 146. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply. DRAFT Page 176 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress pCountryCode
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a buffer where country code is specified associated with the returned information. If the parameters is set to NULL then the function returns global revision information. Pointer to DG_CCTALK_COPY_BUFFER type structure which contains user allocated buffer information. When the function returns it stores requested currency information in the provided buffer.
pCurrencyRev
Description The command requests currency revision information. If no currency code is supplied (CountryCode = NULL) then the global table revision is returned as stored in the header of the note table file. If the country code is supplied then the revision of the first note in the note table with the matching country code is returned, which amy be different to other notes within that country. If the revision number of an unsupported country code is requested then the string 'Unknown' is returned. The command implements header 145. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified DRAFT Page 178 of 226
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
Parameters
iHandle uchDstAddress filename pfnCB
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The name of the file to be uploaded to the device. The function to be called when progress has been made uploading the firmware. If NULL, then no progress callback is made.
Description The command allows uploading a new bill table to a bill/note validator. If pfnCB is non-NULL, then the function it points to is called once at the beginning of the upload and thence for every line and block that is successfully uploaded to the target device. The parameter sofar is the total number of bytes successfully transmitted to the target device, the parameter total is the total number of bytes in the file filename. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
DRAFT
Parameters
iHandle uchDstAddress pBillData
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer of a variable of type DG_CCTALK_BLOCK_DATA, which contains bill table information. Member pData of the structure should point to a buffer with bill information. Member uchDataLen of the structure should specify the size of the buffer.
Description The command sends new bill table information into a validator in a manufacturer neutral format. The data is split into blocks and lines. There are 128 bytes per line, 256 per block up to maximum 256 blocks. This gives total capacity of 256 x 256 x 128 = 8Mbytes. Lines shorter than 128 bytes can be sent. There is no reference to bill type in the data structure - it is assumed that this is represented internally. All this data is passed to the function using DG_CCTALK_BLOCK_DATA structure, which is defined as follows:
typedef struct _DG_CCTALK_BLOCK_DATA { char* pData; unsigned char uchDataLen; unsigned char uchBlock; unsigned char uchLine; } DG_CCTALK_BLOCK_DATA, *PDG_CCTALK_BLOCK_DATA;
where
pData uchDataLen uchBlock uchLine
Pointer to a buffer with bill table information. Number of data bytes located in the buffer pData. Block number where the information should be stored. Line number where the information should be stored.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual The command implements header 144. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example None.
DRAFT
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The command initiates the bill table upgrade procedure. The command implements header 143. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example None.
DRAFT
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The command terminates the bill table upgrade procedure. If a device sends NAK reply then the function returns DGERROR_COMMAND_FAILED error. The command implements header 142. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
DGERROR_INVALID_PARAMETER One of the specified parameters is invalid. DGERROR_BUFFER_TOO_SMALL DGERROR_LINK_CONFIG DGERROR_TIMEOUT DGERROR_COMMAND_FAILED
Failed to acquire access to the stream specified by the handle. The addressed device did not reply. The device returned NAK reply.
Example None.
DRAFT
Parameters
iHandle uchDstAddress pIsUpgradable
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a boolean variable which is set to true if the device's firmware can be upgraded.
Description The command sends a request to a device to determine the upgradability of the device's firmware. The command implements header 141. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example None.
DRAFT
Parameters
iHandle uchDstAddress filename pfnCB
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The name of the file to be uploaded to the device. The function to be called when progress has been made uploading the firmware. If NULL, then no progress callback is made.
Description The command allows upgrading the firmware in a bill/note validator. format of the command is the same as 'Upload bill tables'.
The
If pfnCB is non-NULL, then the function it points to is called once at the beginning of the upload and thence for every line and block that is successfully uploaded to the target device. The parameter sofar is the total number of bytes successfully transmitted to the target device, the parameter total is the total number of bytes in the file filename. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply. DRAFT Page 186 of 226
Parameters
iHandle uchDstAddress pFirmwareData
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer of a variable of type DG_CCTALK_BLOCK_DATA, which contains firmware data. Member pData of the structure should point to a buffer with firmware data. Member uchDataLen of the structure should specify the size of the buffer.
Description This command allows upgrading the firmware in a validator. The format of the command is the same as 'Upload bill table data'. The command implements header 140. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.100
Definition
DG_ERROR cctalk_cmd_begin_firmware_upgrade( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The command initiates firmware upgrade. The command implements header 139. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.101
Definition
DG_ERROR cctalk_cmd_finish_firmware_upgrade( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The command terminates firmware upgrade. If the device sends NAK message as reply then the function returns DGERROR_COMMAND_FAILED error code. The command implements header 138. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
DGERROR_INVALID_PARAMETER One of the specified parameters is invalid. DGERROR_BUFFER_TOO_SMALL DGERROR_LINK_CONFIG DGERROR_TIMEOUT DGERROR_COMMAND_FAILED
Failed to acquire access to the stream specified by the handle. The addressed device did not reply. The device sent NAK message as reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.102
Definition
DG_ERROR cctalk_cmd_switch_encryption( IN int iHandle, IN unsigned char uchDstAddress, IN unsigned int uiEncryptionCode)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The command allows the encryption key or code to be switched to a new value if ccTalk encryption layer is used. The new code takes affect after this function returns. The command implements header 137. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.103
Definition
DG_ERROR cctalk_cmd_store_encryption( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The function instructs a device to store the current encryption code in NV memory. At the next power up, this is the encryption code that needs to be used. The command implements header 136. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.104
Definition
DG_ERROR cctalk_cmd_set_accept_limit( IN int iHandle, IN unsigned char uchDstAddress, IN unsigned char uchCoinsNmb)
Parameters
iHandle uchDstAddress uchCoinsNmb
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Number of coins to be accept before acceptor self inhibits itself.
Description Some applications such as gaming machines require no more than say 3 or 5 coins to be accepted per game play. For a serial coin acceptor this means sending a command to inhibit coin acceptance after a specified number of coins has been entered. When coin throughput is high there is a chance further coins will be accepted due to the latency of the serial communications itself. New coins can only be detected at the credit polling interval and by that time more coins could have passed the accept gate. Set accept limit has a parameter no. of coins which determines how many coins are accepted before the coin acceptor inhibits itself. After self- inhibit, no further coins can be accepted until another Set accept limit command is sent. During self- inhibit, ccTalk event codes Inhibited coin will be returned for each coin entered. It is possible to switch off the self-inhibit mechanism by sending no. of coins equal to zero. The command implements header 135. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified DRAFT Page 192 of 226
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.105
Definition
DG_ERROR cctalk_req_barcode( IN int iHandle, IN unsigned char uchDstAddress, OUT PDG_CCTALK_COPY_BUFFER pData)
Parameters
iHandle uchDstAddress pData
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a structure of type DG_CCTALK_COPY_BUFFER. Member pBufferPtr of the structure must be set to the user allocated buffer. Member uiBufferSize must specify the size of the allocated buffer When the function returns member uiDataCopied is set to the number of returned bytes in the buffer.
Description The function returns the last barcode value as ASCII string. If the scanned barcode was invalid then no data is returned. The command implements header 129. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.106
Definition
DG_ERROR cctalk_req_currency_spec_id( IN int iHandle, IN unsigned char uchDstAddress, OUT PDG_CCTALK_COPY_BUFFER pData)
Parameters
iHandle uchDstAddress pData
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a structure of type DG_CCTALK_COPY_BUFFER. Member pBufferPtr of the structure must be set to the user allocated buffer. Member uiBufferSize must specify the size of the allocated buffer When the function returns member uiDataCopied is set to the number of returned bytes in the buffer.
Description The function returns a 10 character string in the notes table. The command implements header 91 Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.107
Definition
DG_ERROR cctalk_req_note_image( IN int iHandle, IN unsigned char uchDstAddress, IN DG_CCTALK_IMG_SEQ ImageSequence, IN DG_CCTALK_IMG_FMT ImageFormat, IN PDG_CCTALK_COPY_BUFFER pData)
Parameters
iHandle uchDstAddress ImageSequence
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The variable specifies which part of the image should be transfered. DGT_CCTALK_IMG_SEQ_FIRST value is used to initiate the transfer. All the subsequent calls should be made using DGT_CCTALK_IMG_SEQ_NEXT value. The variable specifies the image format (colour or gray) that should be returned and which side if the note (top or bottom). Pointer to a structure of type DG_CCTALK_COPY_BUFFER. Member pBufferPtr of the structure must be set to the user allocated buffer. Member uiBufferSize must specify the size of the allocated buffer When the function returns member uiDataCopied is set to the number of returned bytes in the buffer.
ImageFormat
pData
Description The function requests an image of the last note that passed. through an acceptor. Image data is transferred block by block. Each block consists of 204 bytes. There are 75 blocks for a greyscale image and 225 blocks for a colour image. It is up to the host software to request the correct number of blocks by setting ImageFormat parameter appropriately. ImageFormat variable is of type DGT_CCTALK_IMG_FMT and is defined as follows:
typedef enum _DGT_CCTALK_IMG_FMT { DGT_CCTALK_IMF_GREY_TOP, DGT_CCTALK_IMF_GREY_BOTTOM, DGT_CCTALK_IMF_COLOUR_TOP, DGT_CCTALK_IMF_COLOUR_BOTTOM,
DRAFT
where
DGT_CCTALK_IMF_GREY_TOP DGT_CCTALK_IMF_GREY_BOTTOM DGT_CCTALK_IMF_COLOUR_TOP
Get top grayscale image of the bank note. Get bottom grayscale image of the bank note. Get top colour image of the bank note.
Greyscale images are encoded 1 byte per pixel. A value of 0 represents black and 255 white. Colour images are encoded 3 bytes per pixel. Pixels are sent in RGB triples. First a [ Red ] byte then a [ Green ] byte then a [ Blue ] byte. So each block of 204 bytes contains the data for 68 pixels. The image is transferred to the display device from the serial receive buffer column by column. Each column consists of 102 pixels. There are 150 columns in total for both greyscale and colour images. The command implements header 90. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.108
Definition
DG_ERROR cctalk_cmd_clear_audit( IN int iHandle, IN unsigned char uchDstAddress, IN PDG_CCTALK_COPY_BUFFER pData)
Parameters
iHandle uchDstAddress pData
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. Pointer to a structure of type DG_CCTALK_COPY_BUFFER. Member pBufferPtr of the structure must be set to the user allocated buffer. Member uiBufferSize must specify the size of the allocated buffer When the function returns member uiDataCopied is set to the number of returned bytes in the buffer.
Description The function clears the reset-able audit data within the acceptor's EEPROM. The command implements header 89. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.109
Definition
DG_ERROR cctalk_req_comms_revision( IN int iHandle, IN unsigned char uchDstAddress, IN PDG_COMMS_REVISION pRevision)
Parameters
iHandle uchDstAddress pRevision
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to DG_COMMS_REVISION structure where the function returns the ccTalk level number and the major/minor revision numbers of the communication specification.
Description The function returns the ccTalk level number and the major/minor revision numbers of the communication specification. This is read separately to the main software revision number for the product which can be obtained with a Request software revision command. The command implements header 4. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.110
Definition
DG_ERROR cctalk_cmd_clear_comms( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The function clears cumulative comms status variables (Please see Request Comms status variables command). The command implements header 3. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.111
Definition
DG_ERROR cctalk_req_comms_status( IN int iHandle, IN unsigned char uchDstAddress, IN PDG_COMMS_STATUS pCommsStatus)
Parameters
iHandle uchDstAddress pCommsStatus
A valid handle value that was returned by cctalk_open_link function. The address of the slave device. The pointer to DG_COMMS_STATUS structure where the function returns three cumulative single byte event counters.
Description The function returns three cumulative single byte counters. The host can use his information to evaluate the quality of the link with the slave. For the data to be useful, the counters should be cleared first with the Clear comms status variables command. The DG_COMMS_STATUS structure contains three member uchRXTimeouts, uchRXBytesIgnored, uchRXBadChecksum.
uchRXTimeouts
variables:
The number of times the slave device has timed out on receiving data. This should be 0 for good communication link. which can be stored in the receive buffer, then the number of bytes lost is added to this counter.
uchRXBadChecksum
The counter is incremented each time a receive message is disclosed with an incorrect checksum and a valid slave address.
Failed to allocate memory to complete the operation. The operation completed successfully.
DRAFT
The provided buffer is too small accommodate all of the received data.
to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
3.3.112
Definition
DG_ERROR cctalk_cmd_reset( IN int iHandle, IN unsigned char uchDstAddress)
Parameters
iHandle uchDstAddress
A valid handle value that was returned by cctalk_open_link function. The address of the slave device.
Description The function forces a soft reset in the slave device. The command implements header 1. Errors
DGERROR_NORESOURCES DGERROR_OK
Failed to allocate memory to complete the operation. The operation completed successfully. The provided buffer is too small accommodate all of the received data. to
Failed to acquire access to the stream specified by the handle. The addressed device did not reply.
Example Please see dgcctalk_demo.cpp for more information how to use the command.
DRAFT
4.1
COMPONENT INSTALLATION
The Windows XP Embedded component files are copied to your developer workstation as part of the ccTalk SDK installation. However, the components must still be imported manually into your Windows XP Embedded component database before they can be used. To import the additional components, close any target or component designer applications you have running and start up the Microsoft Component Database Manager in exclusive mode. The Microsoft Component Database Manager can be found under the Microsoft Windows Embedded Studio program group.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual Now hit the Import button and the Import SLD window should appear
Browse to the DPXConnector.sld file (press ) which can be found under the embedded folder where you installed the ccTalk SDK. For example, on a regular installation, this file can be found as C:\Program Files\Innocore ccTalk SDK\embedded\ccTalk SDK.sld. Once you have chosen the file, ensure the Copy repository files to repository root option is ticked and then press Import:
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual The output should resemble the output shown above. You have successfully installed the support for Innocore ccTalk SDK hardware for Microsoft Windows XP embedded. You may now close the Import SLD and Component Database Manager Windows.
DRAFT
4.2
COMPONENTS
The following components are provided. Money Controls ccTalk protocol: provides run-time support for ccTalk communication protocols and application layer. Money Controls ccTalk SDK Sample Programs: this component contains binaries compiled from the example code provided with the SDK. There are two variants: one contains dynamically linked executables, the contains statically linked executables. Money Controls ccTalk SDK Utility Programs: this component contains the utility programs detail in section 5.
The dependencies have been carefully verified so that you should be able to add these into existing configurations without worrying about missing files or components. All components can be located under the Software: System: Networking & Communications category. More details are provided in the following sections.
DRAFT
4.2.1
The Money Controls ccTalk SDK ccTalk Protocol component provides the ccTalk protocol DLL for binaries dynamically linked with dgccTalk.dll. You should include this component in your configuration if you want your application to access the ccTalk API using that DLL. Category Memberships This component is located in these categories: Software: System: Networking & Communications
Services There are no services associated with this component Associated Components There are no components associated. Settings There are no configurable settings for this component. File Resources ccTalk.dll (to c:\windows\system32) Registry Resources There are no registry resources associated with this component Dependencies There are no dependencies. Interface Information This component exports the ccTalk SDK ccTalk API.
DRAFT
4.2.2
The Money Controls ccTalk SDK Sample Programs component provides the various sample programs in pre-compiled form. You should include this component in your configuration if you to be able to debug or test a peripheral from within your embedded configuration. Category Memberships This component is located in these categories: Software: System: Networking & Communications
Services There are no services associated with this component Associated Components There are no components associated. Settings There are no configurable settings for this component. File Resources cctalk_demo.exe (to c:\Program Files\Innocore Gaming ccTalk SDK) cctalk_app_demo.exe (to c:\Program Files\Innocore Gaming ccTalk SDK) Registry Resources There are no registry resources associated with this component Dependencies This component expresses the following dependencies: Money Controls ccTalk SDK ccTalk Protocol
DRAFT
4.2.3
The Money Controls ccTalk SDK Utility Programs component provides the ccutil utility program. You should include this component in your configuration if you to be able to debug or test a peripheral from within your embedded configuration. Category Memberships This component is located in these categories: Software: System: Networking & Communications
Services There are no services associated with this component Associated Components There are no components associated. Settings There are no configurable settings for this component. File Resources Ccutil.exe (to c:\Program Files\Innocore Gaming ccTalk SDK) Registry Resources There are no registry resources associated with this component Dependencies This component expresses the following dependencies: Money Controls ccTalk SDK ccTalk Protocol
DRAFT
5.1
Synopsis
CCUTIL
ccutil p port [options ...] ccutil h | --help ccutil -long-help ccutil -header-help ccutil -v
Description The CCutil command allows command-line access to ccTalk devices. The basic synopsis is shown below but many other options are available and these are outlined below. General command-line options are: -p port baud-rate Sets the communications port over which to communicate with a ccTalk multi-drop bus. On Windows port is generally of the form COMx; on Linux port is generally of the form /dev/tty. The baud-rate for the connection may also be set; if omitted, this defaults to 9600 baud. The character size is always 8 bits, with no parity and one stop bit. -h, --help -v --long-help --header-help Display a terse usage message. Display the version of the ccutil command. Display a full list of options. List all ccTalk headers numbers and the ccutil options which implement that header.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual -a N Set the address of the ccTalk device to which commands will be sent. This address applies only to those command options following it. -i, --info -d Display information about the ccTalk device on the specified port and with the specified address. Enable more information to be displayed. This can be used multiple times. It should come before other options on the command line.
Device Addressing Options: -l HEADER 253 Display a list of ccTalk device addresses. --address-clash HEADER 252 Test to see if a device clash is apparent on the bus. -A, --address-change N HEADER 251 Change the address of the device addressed with a to have the new address N. The device may need a full reset before it starts functioning with the new address. --random-address HEADER 250 Change the address of the device addressed with a to have a new, random address. The device may need a full reset before it starts functioning with the new address. An address probe will have to be performed (option l) to determine the devices new address. --address-mode HEADER 169 Determine and print out the devices address mode. -o, --simple-poll HEADER 254 Perform a simple poll of a device whose address was given by the a option. Doc. ref. 200-338_0.1 DRAFT Page 212 of 226
MoneyControls ccTalk SDK Software Programmers Reference Manual -r, --reset HEADER 1 Reset the device. -C, --clear-comms HEADER 3 Clear the devices communications status Security Options: -P, --enter-pin [code] HEADER 218 Set the pin code to be sent to the device for those commands which require one. The code is a 32-bit number transmitted as four bytes in MSB-first order. The PIN code may be expressed in a format acceptable to the strtol() C function, viz. in decimal, in hexadecimal (if preceeded with 0x) or octal (of preceeded with 0). --change-pin [code] HEADER 219 Change the PIN code for the device to a new one; if an existing PIN has been set then it must have been sent to the device since the last reset for this command to operate. --security-level coin#/bill# level HEADER 181 This command sets the individual acceptance criterion for a given bill or coin on the device. Consult the devices manual for further information. --pump-rnd N HEADER 161 This option pumps the devices random number generator. It should be invoked on coin hoppers before requesting a security code used to encrypt a dispense coins operation.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --cipher-key HEADER 160 This option obtains and displays the current cipher key from a coin hopper. This key can be used to encrypt the command to dispense a coin on hoppers that support the encrypted form of the dispense-coins command (header 168). Note: this command is invoked automatically when the dispense-coins option is used. --switch-encryption Key HEADER 137 This option is used on bill acceptors to inform them of the encryption code to use when communicating. --store-encryption HEADER 136 This option tells a bill acceptor to write the current encryption code into memory for permament use; the device will then automatically use this setting when it powers up in future. Coin-hopper options: --coin-name Sets the communications port over which to communicate with a ccTalk multi-drop bus. On Windows port is generally of the form COMx; on Linux port is generally of the form /dev/tty. The baud-rate for the connection may also be set; if omitted, this defaults to 9600 baud. The character size is always 8 bits, with no parity and one stop bit. --payout-level -E, --emergency-stop Display a terse usage message.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual -e, --enable-hoppper [on|off] HEADER 165 When used with no parameter or with the keyword on this option enables a coin opper, thereby allowing it to dispense coins using command header 168. When used with the keyword off this command disables the hopper, thereby preventing it from dispensing coins. --disable-hopper HEADER 165 This option is identical to invoking the option enablehopper off. --dispense-coins [N] HEADER 168 This option causes a coin hopper to dispense coins. If the hopper has previously been enabled and the correct security settings are supported and in place then the hopper will dispense coins. If the hopper is in single-coin dispense mode then only one coin will be dispensed. --hopper-status HEADER 166 This option returns the status of a hopper in terms of the number of coins dispensed and unpaid. --test-hopper HEADER 163 This option obtains and displays both test status bytes from the hopper. Coin-mech & Bill acceptor options:
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --set-inhibit all | none | [/]N HEADER 231 Sets the inhibit mask for specific coins or bills on the device. If the keyword all is supplied then all bills or coins are configured as inhibited. If the keyword none is supplied then all bills or coins are configured as uninhibited. If one or more parameters N is supplied then bill/coin number N is inhibited. If one or more parameters /N is supplied then bill/coin number N is uninhibited. It is thus possible to set relatively complex patterns of bill/coin inhibitions from a single command:
# ccutil --set-inhibit all /1 /2 /3 # ccutil --set-inhibit none 4 5 6
The first invocation inhibits all coins/bills except those in positions 1, 2 and 3. The second invocation clears the inhibition of all notes but numbers 4, 5 and 6. --master-inhibit [enable|disable] HEADER 228 This option allows configuration of the devices master inhibit flag. If the enable or disable words are used then the devices master inhibit flag is enabled (no bills are accepted) or disabled (bills are accepted) accordingly. If no keyword is supplied then the current master inhibit status is reported. --modify-sorteroverride mask HEDAER 222 This option specifies the sorter override status.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --modify-sorter-paths HEADER 210 This option allows specification of sorter paths for a coin acceptor. Prompts will be given to determine the number of sorter paths (1 or 4) and the sorter numbers for each path. --default-sorter-path N HEADER 189 This option allows specification of the default sorter path for coins accepted by a coin acceptor. --modify-coin-id slot# CCVVVM HEADER 185 This option allow modification of the coin ID for the coin in slot slot# of a coin acceptor which supports changing coin IDs. --select-bank [N] HEADER 179 This option shows or sets the current bank of bill or coin definitions to be used. If the parameter N is supplied, then the current bank is set to N. If the parameter N is not supplied then the current bank number is returned. --modify-inhib inhibit-mask override-mask next-inhibit-mask next-overridemask HEADER 162 This command allows precise control of the coin acceptance behaviour of a coin acceptor. The two inhibit masks are 16-bit values; the two override masks are 8-bit values. Any of these may be expressed in hexadecimal (with lead 0x characters) or decimal.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --route-bill reject | stack | wait HEADER 154 This command deals with a bill just entered into the bill acceptor. Its single parameter operates as follows: Reject return the bill from the device; Stack accept the bill in the stacker or cash-box; Wait defer processing. --stacker-cycle HEADER 147 This option attempts to cycle the stacker (if fitted) on a bill/note acceptor. --accept-limit N HEADER 135 Configures the maximum number of coins or bills accepted by a device. --clear-audit HEADER 89 This option clears any audit data in the device and prints out any data returned by the device. --show-polling-priority HEADER 249 This option shows the polling cycle time for a device. The device event buffer must be polled regularly at an interval not exceeding the polling priority or the device may enter an error state and cease operation until the error is acknowledged. --status HEADER 248 This option shows the status of a coin or bill acceptor as OK, DECK OPEN or COS ACTIVATED. --credit-error-codes HEADER 229 This option shows
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --sorter-status HEADER 221 This option shows the status of the coin sorted in a coin acceptor. --option-flag HEADER 213 This option reads the option flags from the device (if available) and prints them out as a single hexadecimal byte value. --coin-position-mask credit-code HEADER 209 This option shows the position mask determine which coin positions for which a particular credit-code is programmed. --show-sorter-path N HEADER 209 Shows the sorter path for coin type N on coin acceptors. --show-counters HEADERS 225, 226 This option downloads the counter values from the device and displays them. --default-sorter HEADER 188 This option obtains and displays the default sorter for a coin acceptor. --coin-id POS# HEADER 184 This option shows the coin id for a given slot.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual -b, --show-bills HEADER 157 This command shows a list of bills programmed into a bill acceptor. It includes columns showing: * the inhibit status of each bill; * the position of each bill; * the name and value of each bill; * the number accepted for each bill; * the security setting for each bill (if supported). --scaling-factor CC HEADER 156 This command show the scaling factor for the country code CC. --show-bill-events --monitor-bill-events HEADER 159 These two options allow viewing of the events in a bill or coin acceptors event storage buffer. The events are read and displayed with the oldest first. The monitor-bill-events option varies from the showbill-events option in that it continues to read new events from the device until the operator explicitly stops the program. --show-bill-op-mode HEADER 152 This option reads the operating mode status from the device and displays whether the stacker and escrow options are enabled.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --set-bill-op-mode [[no]stacker] [[no]escrow] HEADER 153 This option allows determination of whether the stacker is present and whether escrow mode is enabled. The keyword stacker determines that a stacker has been fitted. The keyword nostacker determines that a stacker has not been fitted. The keywords escrow determines that escrow mode should be used. The keyword noescrow determines that escrow mode should not be used. -show-currency-rev CC HEADER 145 This option shows the revision of currency specification programmed into the device for the currency with country code CC. --show-currency-spec HEADER 91 This option shows which currency is currently programmed into the device. --request-barcode HEADER 129 This command returns the code of the last inserted barcode. --get-note-image top|bottom grey|colour filename HEADER 90 This option allows downloading an image of the last note inserted into the device. Either the top or bottom sensors image can be downloaded and in either greyscale or colour. The file is saved in Microsoft Windows BMP format regardless of any extension to filename. --table-upload File HEADER 143
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --teach-mode-control position orientation HEADER 202 This puts the device into teach mode whereby the features of new notes or coins may be learned. Consult the manual for the specific device on how to use this option. --teach-status HEADER 201 This determines and reports the teaching status of the device. --teach-abort HEADER 201 This option abandons the current teaching session. Device Test options: --self-test HEADER 232 This option sends a self-test request to the device. The device might or might not implement a full self-test immediately. The results of the self-test are reported as two decimal numbers; consult the documentation for the device in question on how to interpret the returned data. --test-solenoids sol# HEADER 240 Display a terse usage message. --test-output mask HEADER 238 This option allows testing of the output lines on devices which have output ports. The mask determines which of up to 8 output lines are pulsed. It is the users responsibility to attach other hardware capable of determine whether the pulse was sent correctly.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --test-lamp lamp# on|off|auto HEADER 151 This allows specific lamps on the device to be tested. The auto option puts the lamp back under the native control of the device. --opto-voltages --operate-motors Motor-mask f|b speed HEADER 146 This allows direct control of the motors (if any) on a device. For the second parameter supply f to operate the motors in the forward direction or b to operate the motors in the reverse direction. The speed parameter works as follows: 0 the default speed 1 the slowest speed 255 the fastest speed. Using setting zero returns control of the motors back to the device. The command does not determine if the motoros are actually operating; it is up to the operator of the device to determine this manually. Miscellaneous options: --database-version HEADER 243 This command reports the programmed into the device. --input-lines-state HEADER 237 This command reports the state of any input lines on the device. --opto-state HEADER 236 This option reports the state of any optical sensors on the target device. database version
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --thermistor-read HEADER 173 This option reports the reading of the devices thermistor as a single integer. --latch-output Mask HEADER 233 This option latches the devices output lines according to mask. --memory-storage HEADER 216 This command reports the amount of storage available on the device and the type of that storage. --memory-write File [start-block#] HEADER 214 This command allows write-access to the devices storage. The data is read from the file called file and written to write-capable storage start at the block startblock#. If the starting block is not specified then writes start at block 0. An error is reported if this is not sufficient storage in the device to write the entire contents of file.
DRAFT
MoneyControls ccTalk SDK Software Programmers Reference Manual --memory-read [start-block# [end-block#]] HEADER 215 This option allows reading the devices memory storage. Memory contents are read from the device and output in binary form to the standard output (console). They may be written to a file using the output redirection operator `> thus:
C:\> ccutil p COM4 a 3 --memory-read >dev3.bin
The output starts at start-block# and end at end-block# 1. If start-block# is not specified then the read starts from block #0. If end-block# is not specified then the read terminates after the last available block of memory. A file containing the output of --memory-read may be supplied as the input to the memory-write option; thus the memory of a given peripheral may be backed up with careful use of these options. --memory-dump [start-block# [end-block#]] HEADER 215 This option is identical to the memory-read option except that the memory contents are output in more human-readable form. --firmware-upload file HEADERS 138-140 This option allows an upgrade of the devices firmware. If the device does not support firmware upgrades then an error is issued. The device might have to be reset manually after this operation. Consult the operating manual for the device for further information. Availability Windows XP and Linux: from ccTalk SDK SDK and Run-time release 1.0.1.
DRAFT
USA
Innocore Gaming Ltd., 10400-4 Pioneer Boulevard, Santa Fe Springs, CA 90670 Tel. +1 (562) 941-5000 Fax. +1 (562) 941-5757 Email: sales@innocoregaming.com
In addition, Innocore provides product information on the Internet at: www.innocoregaming.com For the latest technical information, please refer to the Innocore gaming Knowledge base at; www.innocoregaming.com/support
DRAFT