TMGetFamilySpec Overview Group

The TMGetFamilySpec API call copies information about the current device on the 1-Wire network specified by 'session_handle' into the provided structure Specification. This information is common to all devices of the current 'family' type. The 'family' type of a 1-Wire device is denoted by the first byte of the serial ROM number. For example, the family type of 10 (hex) indicates a DS1920 Temperature iButton.

The information is provided in the form of a structure. This structure includes the number and size of regular pages, the number and size of status pages (EPROM only), maximum communications speed (0-normal speed, 1-overdrive, 2-hyperdrive), the memory type (see full description below) and a description of the family including part number, alternate part number and a brief functional description.

typedef struct {
   unsigned short features[32];
   char description[255];
} Specification;

(This is a packed structure on 1 byte boundaries)

Currently, only the first six unsigned short integers of the features array are defined as follows:

features[0] = regular pages, unsigned least significant byte first
features[1] = bytes per page in regular memory
features[2] = status pages, unsigned least significant byte first
features[3] = bytes per page in status memory
features[4] = max communication speed (regular = 0, overdrive = 1, hyperdrive = 2)
features[5] = memory type (0 = NOMEM, 1 = NVRAM, 2 = EPROM1, 3 = EPROM2, 4 = EPROM3, 5 = EEPROM1, 6 = MNVRAM, 7 = EEPROM2, 8 = NVRAM2, 9 = NVRAM3)
features[6-31] are left for future expansion

Part Types

1.  NOMEM – A part with no user storage space or with non-standard structure. Only TMEX hardware specific functions apply to this type.
2.  NVRAM – A part with non-volatile RAM. All TMEX API’s are supported with the exception of the programming API reserved for EPROM parts and TMExtendedReadPage.
3.  EPROM1 – A part with Electrically Programmable Read Only Memory. Contains an onboard 8-bit CRC data check. All TMEX API’s apply to this type.
4.  EPROM2 – A part with Electrically Programmable Read Only Memory. Contains an onboard 16-bit CRC data check. All TMEX API’s apply to this type.
5.  EPROM3 – A part with Electrically Programmable Read Only Memory. Contains an onboard 16-bit CRC. EPROM2 and EPROM3 differ only by the location and size of TMEX bitmap, the details of which are abstracted into the driver. All TMEX API’s apply to this type
6.  EEPROM1 – Electrically Erasable Programmable Read Only Memory. All TMEX API’s are supported with the exception of the programming API reserved for EPROM parts and TMExtendedReadPage.
7.  MNVRAM – A part with read-only non rolling-over page write cycle counters associated with a portion of the non-volatile RAM. Pages with the 101 extension in the TMEX file name can only reside on counter pages, however any other file name can also reside on counter pages. All TMEX API’s are supported with the exception of the programming API reserved for EPROM parts.
8.  EEPROM2 - Electrically Erasable Programmable Read Only Memory. On board CRC16 for Write/Read memory. Copy Scratchpad returns an authentication byte. All TMEX API’s are supported with the exception of the programming API reserved for EPROM parts.
9.   NVRAM2 - A part with non-volatile RAM. Contains an onboard 16-bit CRC. All TMEX API’s are supported with the exception of the programming API reserved for EPROM parts.
10. NVRAM3 – A part with non-volatile RAM with bit accessible memory. Contains an onboard 16-bit CRC. TMEX hardware specific functions and TMExtendedReadPage apply to this type.

description: An array of characters that contains 3 fields; part number, alternative part number and brief functional description. The fields are delimited by commas and the string is null terminated (i.e.: DS1920,DS1820,Temperature iButton with Trips)


short far pascal TMGetFamilySpec(
long session_handle,        // session handle for the desired 1-Wire network
void far *state_buffer,     // state buffer provided for the 1-Wire network session
Specification far *FamSpec  // pointer to a Specification struct
);

For a description of the above types, see the TMEX Type Descriptions.

Parameters

session_handle

Specifies the session handle returned from the API function TMExtendedStartSession that specifies the desired 1-Wire network port. This parameter is required by most TMEX API functions.

state_buffer

Specifies a pointer to a memory location that TMEX keeps all of the state information for the 1-Wire networks. This parameter is required by most TMEX API functions.

FamSpec

Specifies a Specification struct that will return a description of the 1-Wire device’s family type. See above for more detail.

Return Value

1 => device family information is in buffer 'FamSpec'

<0 => a FILE_OPERATIONS error has occurred

Code Example