iConnection Manager

The iConnection Manager encompasses the Palm serial port, the iConnection module clipped to it and a Dallas Semiconductor iButton (if any) attached to it via a probe. The task of reading and writing to the attached iButton is broken down as follows:

The iConnection manager allocates memory, constructs commands, opens and closes the Palm Serial port, transmits commands and data to the iConnection module via the serial port and receives data and status information from the iConnection module. In order to minimize Palm battery consumption, the iConnection manager keeps the serial port open only long enough to compete a transaction.

The iConnection module responds to the Palm serial port, controls timing and traffic on the 1-Wire iButton interface to generate commands and data for the attached iButton in executing the commands received from Palm and transmits transaction results to the iConnection manager via serial port. The iConnection is powered from the Palm serial port. It is active when the serial port is open and goes into "sleep" mode when the serial port is closed. By design, the iConnection module processes every command received from the iConnection manager to completion even if that process leads to failure or error. Every command starts in the same known initial state. IConnection has no memory of prior transactions.

The Dallas Semiconductor iButton products are documented in literature available via Internet or publications, including flowcharts, data structure and timing diagrams. The iConnection manager and iConnection module are based on Dallas Semiconductor publications.

The iConnection manager takes responsibility for serial port activity including allocating memory and setting transmission parameters, constructing commands and data streams for the iConnection module and obtaining resulting status and data from the iConnection module. In addition in the extension libraries for application buttons such as the Thermochron library, the iConnection manager manipulates raw iButton data to Palm data types and usable structures. Data generated using the extension libraries is compatible with the Scanning Devices Windows-based conduit, dialogs and documents.

The application builder is responsible for the design of the application including the user interface and database requirements.

IConnection Reader Information available to the Palm program

The iConnection ReaderInfoType structure is useful for checking the model number and software version of the reader. This 32-byte information block is permanently embedded in reader hardware and available by calling the ReaderID function. Use this structure to insure that your software is operating with the reader model and version it expects.

typedef struct{ char partNumber[6]; char Version[5]; char Manufacturer[21]; }ReaderInfoType;

iConnection Functions

These iConnection Manager Functions are available

IcnIntegerToPageNumber

Purpose:
Constructs page number for read and write page commands
Prototype:
Handle IcnIntegerToPageNumber(int newPage);
Parameters:
interger page number to be packed.
Result:
handle with two-digit page number.
Comment:
Function converts the passed integer to two ascii characters each a hexidecimal digit 0-9, A-F. Passed integer must be in the range 0 < newPage < 255.
See also:
IcnPageNumberToInteger
Usage:
//allocation Handle newPageH; CharPtr newPageP; int page; Handle myDataH; CharPtr myDataP; Handle errH; Err * errP; //implementation errH = MemHandleNew(sizeof(Err)); errP = MemHandleLock(errH); page=2; newPageH = IcnIntegerToPageNumber(page); newPageP = MemHandleLock(newPageH); myDataH = IcnReadPage(newPageP,false,false,0,errP); //check error and do something with the data if(*errP == 0) { } //release the memory MemHandleFree(newPageH); MemHandleFree(myDataH); MemHandleFree(errH);

IcnPageNumberToInteger

Purpose:
Converts page number for read and write page commands to integer
Prototype:
SWord IcnPageNumberToInteger(CharPtr pageNumber);
Parameters:
pointer to pageNumber
Result:
binary representation of page number.
Comment:
pageNumber consists of two ascii characters, each the equivalent of a hexidecimal digit, 0-9, A-F. If not in this format, function returns 0. Function is useful for calculating page extents of data.
Usage:
//allocation Handle currentPageH; CharPtr currentPageP; Handle newPageH; CharPtr newPageP; int numberOfPages; int firstPage; Handle myDataH; CharPtr myDataP; Handle errH; Err * errP; errH = MemHandleNew(sizeof(Err)); errP = MemHandleLock(errH); //implementation - calculate end page to read 25 pages of data numberOfPages=25; currentPageH = MemHandleNew(10); currentPageP = MemHandleLock(currentPageH); StrCopy(currentPageP,"10"); newPage = IcnPageNumberToInteger(currentPageP) + numberOfPages; newPageH = IcnIntegerToPageNumber(newPage); newPageP = MemHandleLock(newPageH); myDataH = IcnReadPageRange(currentPageP,newPageP,false,false,0,errP); myDataP = MemHandleLock(myDataH); //check error and do something with the data if(*errP == 0) { } //release the memory MemHandleFree(newPageH); MemHandleFree(currentPageH); MemHandleFree(myDataH); MemHandleFree(errH);

IcnReadButtonID

Purpose:
Read a button's lasered ROM
Prototype:
Handle IcnReadButtonID(void);
Parameters:
None
Result:
returns a handle to the data read from button
Comment:
Function allocates sufficient memory, issues read command, moves data into the memory location and returns a handle to the data. On return, lock the handle to obtain a pointer to the data. If an error is detected, function moves an error code ascii "0" to each byte of the ID data field and ascii "XX" to the button Family data field (not a valid button ID). On return, check the error code and lock the handle to obtain a pointer to the data.
Usage:
//declaration Handle buttonDataH; CharPtr buttonDataP; //call function to read buttonID, lock the returned handle and get a pointer to the data. buttonDataH= IcnReadButtonID(); buttonDataP=MemHandleLock(buttonDataH); if((StrNCompare(buttonDataP+12,"XX",2)) //check for error { // do something with the data, display it, check it, store it, etc } else { //handle or report the error } //release the memory MemHandleFree(buttonDataH);

IcnReadExtendedButtonID

Purpose:
Read a button's lasered ROM including the CRC byte
Prototype:
Handle IcnReadExtendedButtonID(void);
Parameters:
None
Result:
returns a handle to the data read from button
Comment:
This function is similar to ReadButtonID() with the exception that the iButton ROM CRC data byte is included in the returned data. Function allocates sufficient memory, issues read command, moves data into the memory location and returns a handle to the data. On return, lock the handle to obtain a pointer to the data. If an error is detected, function moves an error code ascii "0" to each byte of the ID data field and ascii "XX" to the button Family data field (not a valid button ID). On return, check the error code and lock the handle to obtain a pointer to the data.
Usage:
//declaration Handle buttonDataH; CharPtr buttonDataP; //call function to read buttonID, lock the returned handle and get a pointer to the data. buttonDataH= IcnReadExtendedButtonID(); buttonDataP=MemHandleLock(buttonDataH); if((StrNCompare(buttonDataP+14,"XX",2)) //check for error { // do something with the data, display it, check it, store it, etc } else { //handle or report the error } //release the memory MemHandleFree(buttonDataH);

IcnReaderCheck()

Purpose:
Verify that a reader is attached and responding to commands
Prototype:
Boolean IcnReaderCheck(void);
Parameters:
None
Result:
returns true if the reader responds, false otherwise
Comment:
Function transmits a status request to the reader, expecting a response. If a response is received, function returns true. If no response is received within the time-out period, the function returns false.
Usage:
//allocation //No memory allocation or variable declaration is required //call function as the argument of an if statement. if(IcnReaderCheck()) { //do something to indicate that the reader responded OK } else { //report or handle a reader not attached or not working situation }

IcnReaderID

Purpose:
Identify the reader attached to Palm
Prototype:
Handle IcnReaderID(void);
Parameters:
none
Results:
returns a handle to ReaderInfoType filled in by the function.
Error codes:
If no response or an incomplete response is received from the reader within the function time-out period, the Version field returned is "0".
Comment:
Use this function to determine model, software version and manufacturer of the attached reader. 32-bytes are embedded in the reader's on-board non-volatile memory. See the definition of ReaderInfoType structure for allocation of the memory. For example, iConnection 3303A has the following data: partNumber = "3303A" Version = "V2.0" Manufacturer = "Scanning Devices Inc"
Usage:
//declaration Handle readerInfoH; ReaderInfoType * readerInfoP; //call function, lock the returned handle to get a pointer to the data. readerInfoH= IcnReaderID(); readerInfoP=(ReaderInfoType *)MemHandleLock(buttonDataH); //check if data is valid if(StrCompare(&readerInfoP->Version,"0")!=0) { // do something with the data, display it, check it, store it, etc } else { //handle or report the error } //release the memory MemHandleFree(readerInfoH);

IcnReadPage

Purpose:
Read one page (32 bytes) from button
Prototype:
Handle IcnReadPage(CharPtr pageID, Boolean CRC, Boolean OD, ULong keyCode, Err * errP)
Parameters:
pageID 2 character identifier, CRC if true, read using button-generated CRC, if false read without CRC OD if true, operating button at OverDrive speed, if false, operate at regular speed keyCode encryption key, keyCode=0 for no encryption errP pointer to error code returned by function
Result:
returns a handle to the data read from button
Error codes:
0 no error icnErrIncomplete insufficient data received icnErrTimeout no response from reader in prescribed time icnErrBadPageNumber could not compute amount of memory to allocate from page numbers provided. serErrBadParm serial port invalid or missing parameter serErrTimeout serial port interbyte timeout exceeded serErrLineErr unrecoverable line error occured memErrNotEnoughSpace memory manager error in allocation
Comment:
Function attempts to allocate memory of sufficient size for data, issues read command, moves data into the memory location and returns a handle to the data. If an error is detected, function moves error code to specified pointer. On return, check the error code and lock the handle to obtain a pointer to the data. Pointer pageID consists of two characters, each character the equivalent of a hexidecimal digit, 0-9, a-f. This allows addressing 256 pages, 00 to ff. This nomenclature maintains consistency with Dallas Semiconductor documentation. The calling program is responsible for determining if attached button supports overdrive or internally generates CRC data. For example, calling this function with CRC=true to read a button without CRC support will return an error.
Usage:
//declaration Handle buttonDataH; CharPtr buttonDataP; VoidHand errH; VoidPtr errP; errH = MemHandleNew(sizeof(Err)); errP = MemHandleLock(errH); //call function, lock the returned handle and get a pointer to the data. buttonDataH= IcnReadPage("00",false,false,0, errP); buttonDataP=MemHandleLock(buttonDataH); if(!*errP) { // do something with the data, display it, check it, store it, etc } else { //handle or report the error } //release the memory MemHandleFree(buttonDataH);

IcnReadPageRange

Purpose:
Read consecutive pages (each 32 bytes) from button
Prototype:
Handle IcnReadPageRange(CharPtr startPageID, CharPtr endPageID, Boolean CRC, Boolean OD, ULong keyCode, Err * errP);
Parameters:
startpageID 2 character page address, endPageID 2 character page address, CRC if true, read using button-generated CRC, if false read without CRC OD if true, operating button at OverDrive speed, if false, operate at regular speed keyCode encryption key, keyCode=0 for no encryption errP pointer to error code returned by function
Result:
returns a handle to the data read from button
Error codes:
0 no error icnErrIncomplete insufficient data received icnErrTimeout no response from reader in prescribed time icnErrBadPageNumber could not compute amount of memory to allocate from page numbers provided. serErrBadParm serial port invalid or missing parameter serErrTimeout serial port interbyte timeout exceeded serErrLineErr unrecoverable line error occured memErrNotEnoughSpace memory manager error in allocation
Comment:
This function is an effective way to read a large amount of data quickly. Function computes data size and allocates sufficient memory. If endPageID is not greater than or equal to startPageID, function returns icnErrBadPageNumber error, makes no attempt to read. Function issues read command, moves received data into the memory location and returns a handle to memory. If an error is detected, function moves error code to specified pointer. On return, check the error code and lock the handle to obtain a pointer to the data.

startPageID and endPageID each consist of two ascii characters, each character the equivalent of a hexidecimal digit, 0-9, a-f. This allows addressing 256 pages, 00 to ff. This nomenclature maintains consistency with Dallas Semiconductor documentation. Calling program is responsible for determining if attached button supports over drive, internally generates CRC data and page range is valid. For example, calling this function with CRC=true to read a button without CRC support will return an error.

Usage:
//allocation Handle buttonDataH; CharPtr buttonDataP; VoidHand errH; VoidPtr errP; errH = MemHandleNew(sizeof(Err)); errP = MemHandleLock(errH); //call function to read 256 pages, lock the returned handle and get a pointer to the data. buttonDataH= IcnReadPageRange("00","ff", false, true, errP); buttonDataP=MemHandleLock(buttonDataH); if(!*errP) { // do something with the data, display it, check it, store it, etc } else { //handle or report the error } //release the memory MemHandleFree(buttonDataH); MemHandleFree(errH);

IcnWritePage

Purpose:
Write one page (32 bytes) to the iButton with verification.
Prototype:
Err IcnWritePage(CharPtr pageID, Boolean OD, Word keyCode, CharPtr pageDataP);
Parameters:
pageID 2 character page number, OD if true, operate button at OverDrive speed, if false, operate at regular speed keyCode encription key, keyCode=0 for no encription pageDataP pointer to data to write
Result:
returns an error code: 0 if no error icnErrIncomplete insufficient data received icnErrTimeout no response from reader in prescribed time icnErrBadPageNumber could not compute amount of memory to allocate from page numbers provided. serErrBadParm serial port invalid or missing parameter serErrTimeout serial port interbyte timeout exceeded serErrLineErr unrecoverable line error occured memErrNotEnoughSpace memory manager error in allocation
Comment:
Transmits 32 bytes (encrypted by keyCode if non-zero) to iConnection to be written to iButton at the specified page. On return, check the error code to make sure the button has written the data correctly.

pageID consists of two characters, each character the equivalent of a hexidecimal digit, 0-9, a-f. This allows addressing 256 pages, 00 to ff. This nomenclature maintains consistency with Dallas Semiconductor documentation.

Calling program is responsible for determining if attached button supports overdrive and page ID is valid. For example, calling this function with pageID = ff on a button with only one page will return an error.

Note on verification:
Data is transmitted from iConnection manager to iConnection via serial port without verification. IConnection writes data to iButton scratchpad, reads-back data from iButton scratchpad to verify that transmission on 1-wire between iConnection module and iButton occurred without error and if correct, commands iButton to write scratchpad to specified page. Comparision occurs in the iConnection module. Data is not returned to Palm for verification prior to issuing scratchpad write command to iButton. If your application requires verification all the way back to Palm, follow the IcnWritePage command with an IcnReadPage command to recover the data and make your comparison in Palm to verify. Additional time required for this step is longer than if a single transaction were implemented with verification by Palm, but does not impose the extra processing on all applications. Contact Scanning Devices Inc. if you need a special function in this area.

Usage:
//declaration and allocation Handle buttonDataH; CharPtr buttonDataP; Handle pageH; CharPtr pageP; Err errorCode; buttonDataH=MemHandleNew(50); buttonDataP=MemHandleLock(buttonDataH); StrCopy(buttonDataP,"Here is some data to store on page 10"); //notice that although string length is 37 characters, only the //first 32 will be written to the button pageH=MemHandleNew(10); pageP=MemHandleLock(pageH); StrCopy(pageP,"1A"); //page 10 //call function, check the returned errorcode. errorCode=IcnWritePage(pageP,false,false,buttonDataP); if(errorCode == 0) { StrCopy(buttonDataP,"Button saved OK"); // do something with the data, display it, check it, store it, etc } else { StrCopy(buttonDataP,"Button reported Error"); //handle or report the error } //release the memory MemHandleFree(buttonDataH); MemHandleFree(pageP);