Citect for Windows Driver Specification

Transcription

1 Citect for Windows Driver Specification ASCII Driver Author Date Comment Bruce Kinchin 9/1/97 Original Colin Ferguson 6/3/98 Fixes from Graeme Sutton Graeme Sutton 7/12/99 Additional information Peter Geagea Cosmetic changes

2 Contents 1. INTRODUCTION Scope Outline QA Developers Guidelines Accredited Drivers Independent Drivers Accreditation process 5 3. TARGET DEVICE(S) AND PROTOCOL Introduction Device Manufacturer Device Definition Communications Method Communications/Hardware Configuration Special Requirements Maximum Request Length 7 4. PROTOCOL REQUIREMENTS Introduction Initialising the Board Initialising the Port Initialising the IO Device(s) IO Device Online Test State Flow Description Message Structure Error Handling 9 5. USER INTERFACE Introduction Driver Name Boards Form Ports Form 10 ASCII.DOC 2

3 5.5 IO Devices Form Protocol Address Pulldown lists Help IO Device Variable Types PROTDIR.DBF Parameters and INI options Standard Parameters Driver Specific Parameters Examples Driver Specific Errors Driver Error Help Debug Messages Stats Special Counters Hints and Tips BASIC TESTING Introduction Procedure PERFORMANCE TESTING Introduction REFERENCES References Contacts 20 ASCII.DOC 3

4 1. Introduction 1.1 Scope. This document follows the development of the new driver. It serves as a functional specification, design specification and test specification. 1.2 Outline. The specification is broken down into the following sections: Section 1 - Introduction. This section defines the scope of a board driver specification and outlines the items addressed by the specification. Section 2 - Quality Assurance. The QA section defines the requirements and procedures for Quality Assurance Accreditation. It is important you read this if you want your driver integrated into Citect. Section 3 - Physical Communication Method. The Physical Communication Method section defines the physical communication method supported, hardware/software suppliers, how the method is setup, any wiring diagrams involved etc. Section 4 - Protocol Requirements. The Protocol Requirements section details the technical considerations required or incorporated by the driver. Section 5 - User Interface. The User Interface section defines how the user will see and setup the driver in Citect. Section 6 - Basic Testing. The Basic Testing section defines the items that should be addressed in basic testing by the developer. Section 7 - Performance Testing. The Citect Testing Department of CIT uses the Performance Testing section in full testing of the driver. Once complete, this will provide details on the reliability and stability of the driver, and point out where the driver needs to be improved. Section 8 - References and Contacts. The References and Contacts section should be used as a record of reference materials and contacts used in developing this driver. ASCII.DOC 4

5 2. QA 2.1 Developers Guidelines These guidelines are meant as a rough indication of what options there are for developing Citect drivers and the advantages of these options. It is not a technical discussion of options, rather a marketing guideline. Drivers fall into two categories, Accredited and Independent Accredited Drivers. Accredited drivers are those drivers that have been put through the CIT Driver QA Scheme and have passed all stages of this accreditation process. It is a precondition to becoming accredited that these drivers will be included with Citect in a normal release. Accreditation has the following advantages: 1. The driver will be included in the product and a certificate stating this driver has achieved Accreditation will be sent to the developer. 2. Accredited drivers will be honoured as part of the product in terms of Citect Support and receive full cooperation between Citect Support personnel and the developer. On the other hand, independent driver problems will immediately be referred on to the original developer. 3. Help documentation and Express Wizards is provided, free of charge, for all Accredited drivers. Help documentation for Independent drivers is the responsibility of the developer. 4. Accreditation is included in the cost of the DDK. A high level of quality is expected and if this is not met the driver will not be accredited. 5. Citect Customers see value in Accredited drivers, as there is some assurance that the driver will operate as documented. Some customers may only accept Accredited drivers Independent Drivers. Independent drivers are those that have not completed or are not intended to complete the Accreditation process. These drivers will not be included in Citect, nor will Citect Support personnel give them any support. We would request all drivers be sent to CIT regardless, even if they are not to be included in the product. If this is done, we can try to ensure compatibility with future versions of Citect. Independent Drivers have the following advantages: 1. Drivers may be written by or for an end user giving them an edge over their opposition by using Citect. 2. Drivers may be developed as part of a package offered by System Integrators or including preconfigured packages etc., thereby maintaining the intellectual and financial investment. This would be similar to value added or OEM style marketing. 2.2 Accreditation process The following check list defines the QA steps for generating a new driver. This procedure must be followed for drivers to be integrated into Citect. It is advisable to ensure that items before each checkpoint are complete before proceeding to avoid rework if changes are required. Description Person Date ASCII.DOC 5

6 1 This specification document is written. Bruce Kinchin 9/1/97 2 Specification reviewed and accepted by CiT Driver Development. Bruce Kinchin 10/2/97 At this checkpoint coding is ready to be commenced. 3 Driver coded. 4 Code and specification reviewed and accepted by CiT Driver Development. 5 Testing with connection project, and performance test. 6 Driver integrated into Citect source and built. 7 Documentation is written. 8 Documentation reviewed. At this checkpoint coding is done and the driver is available as a beta. 9a 9b 9c Full testing is carried out. Performance testing is carried out. Specification and documentation updated from testing/performance tests At this checkpoint the testing is complete. 10a 10b 10c 10d Review for completeness by developer, tester, documenter and CiT Driver Development Add driver to install disks Add driver to drivers database Support notified of new driver for training purposes 11 Sales notified of new driver The driver is now finished. The hand over of a driver requires that all the above steps are completed and checked off. ASCII.DOC 6

7 3. Target Device(s) and Protocol 3.1 Introduction This driver targets simple ASCII based protocols that do not have a dedicated driver but need the speed and functionality provided by a normal Citect driver. While this functionality can sometimes be provided by Cicode manipulation of COM ports etc., the functionality sought is often generic between different ASCII based protocols. Some characteristics of protocols from which similarities are derived are: Point-to-Point OR Multi-Drop communications (inferring source and/or destination addresses) Checksum calculations Start and end of message delimiters Command driven request / response method OR Unsolicited response Each of these characteristics usually appears as a field within the message format. Without concentrating on the interpretation of each field, this driver aims to break down message formats into easily useable components, without excess Cicode. The Cicode can then be used solely for the interpretation of each field. As a requirement it is very generic, and there are no manufacturer specific details. 3.2 Device Manufacturer None, this is a generic protocol and has no manufacturer affiliation. 3.3 Device Definition Includes devices with a simple ASCII based protocol (eg. Bar code readers, weigh stations etc.). 3.4 Communications Method Serial (any using these physical layers: RS232, RS485, TCPIP, and ARCNET) 3.5 Communications/Hardware Configuration Refer to manufacturers documentation for details on wiring diagrams, I/O device settings, software setup etc. 3.6 Special Requirements Refer to manufacturers documentation for details on any special requirements. 3.7 Maximum Request Length 2048 ASCII.DOC 7

8 4. Protocol Requirements 4.1 Introduction This section documents all the requirements of the protocol itself. 4.2 Initialising the Board Standard serial board initialisation. 4.3 Initialising the Port Standard serial port initialisation. 4.4 Initialising the IO Device(s) The IO device is be initialised by cicode, if required, by the user after the device is online. 4.5 IO Device Online Test The device is permanently online. 4.6 State Flow Description All incoming characters will be placed in a buffer. The INI variable InputBufferLength sets the size of the incoming buffer. This buffer will then be scanned (unless a previous scan has not been operated on) each polltime, or on an interrupt basis if polltime is zero, as for a normal driver. Each scan will compare the buffer against all available input templates. The first occurrence of a matching template of any template in the buffer will stop the comparisons, and the string that matches the template will be extracted from the buffer. All characters before the matched template will be discarded, as no other matching template was found in these characters. The string will be then decomposed into the registers assigned by the INI settings defining the incoming message. A data available flag will then be set indicating which template has data available. The user places all outgoing messages in the registers. When the data ready flag is set, a message will be formed from the registers according to the INI settings defining the outgoing message. Once the message is formed it will immediately be sent out using the COM functions. The data ready flag will be reset once the message is sent. The following two flow paths detail the course of action to be taken for incoming and outgoing data: ASCII.DOC 8

9 Incoming message Outgoing message Match string from buffer Data Ready flag is set Decompose into parts Compose message Set Data Available flag Send message Reset Data Ready flag 4.7 Message Structure The outgoing message structure is the combination of the various output fields. The incoming message structure is the combination of the various input fields. Each message, incoming or outgoing, can be up to 255 characters in length. STRING The string can be up to 255 characters. 4.8 Error Handling If a INI entry doesn't make sense, or if when taken together they don't make sense then the driver will return a driver specific error. For example, if there is no Input templates defined, raise a driver specific error. The overflow condition occurs when the number of characters in the buffer equals the buffer length (ie. no more room in buffer.). New characters arriving when there is no room in the input buffer will be discarded. ASCII.DOC 9

10 5. User Interface 5.1 Introduction This section defines how the user will see the driver. This relates directly to how the Citect forms need to be filled out and any special INI options. For the kernel, the debug trace messages and the Stats.Special counters are documented. 5.2 Driver Name ASCII 5.3 Boards Form Standard serial board setup 5.4 Ports Form Standard serial ports setup 5.5 IO Devices Form Protocol ASCII Address None. 5.6 Pulldown lists Help The following entries should be included in the Citect Help.DBF spec file. TYPE DATA FILTER PROTOCOL ASCII PROTOCOL ASCII1 PROTOCOL ASCII2 ASCII.DOC 10

11 5.7 IO Device Variable Types IO Device Type Citect data type Citect type data Description/Special Valid Ranges Usage/Limitations/ Input Fields In STRING Read only. These fields are not cleared once the Data Available message is reset. Data Available DAt DIGITAL Read / Write. One of these digitals goes high when there is data available for the respective template. The user (eg. With Cicode) should reset this once the data has been successfully read so that the buffer is cleared and new data can be interpreted by the driver. Output Fields On STRING Read / Write. These fields are not cleared once a message has been sent. Data Ready DRt DIGITAL Read / Write. One of these digitals should be set high when the data for the respective template is ready to be composed into a message and be sent. The driver will reset this once the message has been sent. Number of characters in Input buffer. Number of strings read Number of strings written Number of bad string formats SCOUNT INT Read / Write. If zero is written into this register, then Input buffer will be flushed. SREAD INT Read / Write. If zero is written into this register, then register will be reset. SWRITE INT Read / Write. If zero is written into this register, then register will be reset. SBAD INT Read / Write. If zero is written into this register, then register will be reset. Timeout TIMEOUT DIGITAL Read / Write. If no characters have been received in LongTimeout time then this flag is set. It is reset by an incoming character, or by the user resetting this bit. Overflow OVERFLOW DIGITAL Read / Write. If an overflow occurs in the input buffer, this digital is set high. The user (eg with cicode) should reset this when acknowledged. Where n is the field number. 0 (zero) is reserved for the full message. t Is the template number. Note: Input template 1 does not equal output template PROTDIR.DBF TAG FILE BIT_BLOCK MAX_LENGTH OPTIONS ASCII.DOC 11

12 ASCII ASCII x1007 ASCII1 ASCII x1007 ASCII2 ASCII x Parameters and INI options Standard Parameters Block Not used by driver. Set at 128. Delay Not used by driver. Set at 0. MaxPending 1 Polltime 200 (ms) Use to check COM port for incoming messages. Timeout Not used by driver. Unit permanently online. Set at 1000 (ms). Retry Not used by driver. Set at 0. WatchTime Not used by driver. Set at Driver Specific Parameters To allow for multiple instances of this driver, if the protocol name is defined with a following number (eg. ASCII2) then the driver will look in the corresponding parameter group (eg. [ASCII2] ) [ASCII] SetOfflineOnTimeout When set to 1, allows to put a unit offline when Read reaches a timeout. Default value is 0. ValidDelay The minimum time period that the datatype DA must maintain logic 0 between messages. Default = 1000mS. LongTimeout Used by the driver to set the maximum time (in milliseconds) between receiving characters before setting the datatype TIMEOUT to true. Default = (ms). InputBufferLength This is the actual size of the input buffer to which incoming characters are appended. When this buffer overflows, the datatype Overflow will be set. InputTemplates Defines a list of templates names used for incoming messages. Each template is delimited by a comma (eg InputTemplates = InputTemplateName, InputTemplateName, InputTemplateName,... ) OutputTemplates Defines a list of templates names used for outgoing messages. Each template name is delimited by a comma (eg OutputTemplates = OutputTemplateName, OutputTemplateName, OutputTemplateName,... ) [InputTemplateName] TemplateNumber TemplateFormat Defines the template number as defined by t in the section IO Device Variable types. Defines a list of field names used for matching incoming messages. Each field name is delimited by a comma (eg. TemplateFormat = FieldName, FieldName, FieldName,...). Each field used in a template must have a different name. Different templates can reuse the same field names. [FieldName] FieldNumber Defines the field number used for this field as defined by n in the section IO Device Variable types. On input the value of -1 should be used if this field is not stored; on output the value of -1 should be used if the field is obtained from the literal value of FieldFormat options 2) or 3) ASCII.DOC 12

13 FieldFormat FieldPadding Defines a list of format options for this field, each delimited by a comma (eg. FieldFormat = FormatOption, FormatOption, FormatOption, FormatOption, etc.). It may include three types of information: 1) length specifier denoted by {number} where number is the number of characters this part of the field requires. If number is omitted, then this part of the field is a variable length, but there MUST be some delimiter to the field in this case. 2) simple printable characters enclosed in square brackets (eg. [;] etc.). The need to use square brackets as a character is the use of two square brackets (eg. [[). 3) special characters denoted by the ^ symbol followed by the Hexadecimal value. (eg. ^0x02) Note: The, (comma) symbol has special meaning for this driver and should be referred to as ^0x2C. If defined, this INI option details the hex code of the character to use as padding for the field for outgoing messages if a) the field format is of the type {number} and b) the actual number of characters defined by the field is more than provided by the user. (e.g.. FieldPadding=0x20 will pad the field with spaces.) Examples Example 1 Only one incoming message type: STX DATA STX = 1 character DATA = 10 characters [ASCII] InputTemplates = READ [READ] TemplateNumber = 1 TemplateFormat = STX, DATA [STX] FieldNumber = 1 FieldFormat = {1} [DATA] FieldNumber = 2 FieldFormat = {10} Notes: 1. FieldFormat for STX could also equal ^0x02 2. Variable Tag with address I0 has STX and DATA 3. Variable Tag with address I1 has STX 4. Variable Tag with address I2 has DATA Example 2 Only one incoming message type containing variable length fields: ASCII.DOC 13

14 IDENT = variable length F1 = 1 fixed character DATA = variable length CR = 1 fixed character [ASCII] InputTemplates = T1 [T1] TemplateNumber = 1 TemplateFormat = IDENT, F1, DATA, CR [IDENT] FieldNumber = 1 FieldFormat = {} [F1] FieldNumber = -1 FieldFormat = [;] [DATA] FieldNumber = 2 FieldFormat = {} [CR] FieldNumber = -1 FieldFormat = ^0x0D Notes: 1. Variable Tag with address I0 has IDENT, F1, DATA and CR 2. Variable Tag with address I1 has IDENT 3. Variable Tag with address I2 has DATA eg if you received 1234;99^0x0d. I1 gets assigned 1234 and I2 gets assigned 99. Example 3 Two message types, one is a normal message, the other an error message: Normal STX 1 DATA CRC ETX Error STX 2 ERROR CRC ETX DATATYPE = 1 character ERRORTYPE = 1 character DATA = 10 characters ERROR = 4 characters CRC = 2 characters ETX = 1 character [ASCII] InputTemplates = NORMAL, DATA, ERROR ASCII.DOC 14

15 [DATA] [NORMAL] TemplateNumber = 1 TemplateFormat = DATATYPE, DATA, CRC, ETX [ERROR] TemplateNumber = 2 TemplateFormat = ERRORTYPE, ERROR, CRC, ETX [DATATYPE] FieldNumber = -1 FieldFormat = ^0x02,[1] [ERRORTYPE] FieldNumber = -1 FieldFormat = ^0x02,[2] [DATA] FieldNumber = 1 FieldFormat = {10} [ERROR] FieldNumber = 2 FieldFormat = {4} [CRC] FieldNumber = 3 FieldFormat = {2} [ETX] FieldNumber = -1 FieldFormat = ^0x03 Notes: 1. Variable Tag with address I0 has the whole message 2. Variable Tag with address I1 has DATA 3. Variable Tag with address I2 has ERROR 4. Variable Tag with address I3 has CRC 5. DATATYPE, ERRORTYPE and ETX are ignored. 6. Variable Tag with address DA1 will go high if the DATA message is matched. 7. Variable Tag with address DA2 will go high if the ERROR message is matched. Example 4 Only one outgoing message type: STX DATA CRC STX STX = 1 character DATA = 10 characters CRC = 2 characters ETX = 1 character [ASCII] OutputTemplates = WRITE [WRITE] TemplateNumber = 1 TemplateFormat = STX, DATA, CRC, STX ASCII.DOC 15

16 [STX] FieldNumber = -1 FieldFormat = ^0x02 [DATA] FieldNumber = 1 FieldFormat = {10} [CRC] FieldNumber = 2 FieldFormat = {2} [ETX] FieldNumber = 2 FieldFormat = ^0x03 Notes: 1. The STX character (0x02) will be put into the outgoing message without requiring a Variable tag defined. 2. The user should place the Data into Variable Tag with address O1. 3. The user should place the CRC calculation data into Variable Tag with address O2. 4. The ETX character (0x03) will be put into the outgoing message without requiring a Variable tag defined. Example 5 - cicode usage FUNCTION Read() INT hdbase; INT herrors; hdbase = DevOpen("BarCodes", 1); herrors = DevOpen("Errors", 1); While (Shutdown = FALSE) DO IF DataBuffReady then END DevAppend( hdbase ); DevSetField( hdbase, "BARCODE", Barcode ); DevSetField( hdbase, "TIME", TIME(1) ); DataBuffReady = 0; IF ErrorBuffReady then DevAppend( herrors ); DevSetField( herrors, "ERRORCODE", ErrorCode ); DevSetField( herrors, "TIME", TIME(1) ); ErrorBuffReady = 0; END END SLEEPMS(200); REREAD(1); END 5.10 Driver Specific Errors ASCII.DOC 16

17 Driver Error Code (Hexadecimal) Mapped to (Generic Error label) Meaning of Error Code Queue Overrun 5.11 Driver Error Help The following entries should be included in the Citect ProtErr.DBF spec file. PROTOCOL MASK ERROR MESSAGE REFERENCE ACTION COMMENT 5.12 Debug Messages This is user defined. Debug messages are protocol dependent where this driver is protocol independent Stats Special Counters Number Label Purpose/Meaning of this counter 0 SWRITE Number of string writes performed 1 SREAD Number of string reads performed 2 SBAD Number of bad string formats 3 SCOUNT Number of strings in input buffer Hints and Tips {Any quirks or inconsistencies discovered in the development that users will need to set up communications or overcome problems} ASCII.DOC 17

18 6. Basic Testing 6.1 Introduction The programmer will perform a minimum level of testing that is outlined here. A sample Project is available which can be used as a starting point for the programmer s test Project. When the programmer has completed basic testing and debugging this Project should by backed up and supplied to the Citect Testing department. 6.2 Procedure Basic testing should cover the following points. On startup the IO Device comes online without errors. The driver supports IO Devices of addresses as documented in the specification. The driver reports the IO Device offline when the IO Device is a) powered down, b) disconnected. The driver will re-establish communication with the IO Device after a) power cycle, b) disconnection/ reconnection. Confirm that retries (if supported) and error reporting operate correctly. The driver reads all the device data types documented as readable in this specification. The driver writes to all the device data types documented as write-able in this specification. The driver reads and writes all data formats supported by the protocol, ie DIGITAL, INT, LONG, REAL, BCD, LONG_BCD. Test the limit of the IO Devices request size, this should be done for at least DIGITAL and an INT data formats. Let the driver run over night and check that no retries or other errors have occurred. If a multidrop or network protocol and if the hardware is available then the protocol should be tested with more than one IO Device connected. ASCII.DOC 18

19 7. Performance Testing 7.1 Introduction No performance tests are required for this driver. ASCII.DOC 19

20 8. References 8.1 References Accusort bar code reader specification. 8.2 Contacts Bruce Kinchin, Citect Device Driver Manager. Ci Technologies Pty Ltd West St. Pymble NSW 2073 Int l Ph: Int l Fax: CitectDrivers@cit.com.au David Thompson Micromax (supplier of Accusort bar code readers) Int l Ph: Int l Fax: Andrew Heard David Heatley Verdant Pty Ltd 1/45 Goulburn Street, Hobart, 7000, TAS Australia Int l Ph: Int l Fax: Dave_Heatley@msn.com Bruce Innocent Int l Ph: Int l Fax: Bruce.I@wacco.com.au ASCII.DOC 20