🏠 vdwulp.github.io

📚 Arduino iButtonTag Library

Reference documentation

• This iButtonTag library reference documentation describes all available types, constants and functions.
• For more general information visit Arduino iButtonTag Library.
• All current constants are used to indicate iButton (re)writable tag types and their valid value range. These are used in functions related to writing identification codes.
• Apart from the constructor, available functions can be arranged in three groups:
  • Reading identification code(s): readCode, readCodes, nextCode
  • Writing identification code: writeCode, detectWritableType
  • Utility: testCode, equalCode, printCode, updateChecksum

Types

iButtonCode

Type representing an iButton identification code of eight bytes.

The iButtonCode type can be used as een array of eight uint8_t values. The first byte represents a OneWire family code indicating a iButton/device/sensor type. The middle six bytes are a (unique) identification code. The last byte is a checksum over the family and identification codes.

Constants

IBUTTON_UNKNOWN

Indicates unknown iButton tag type. Returned from detectWritableType, argument to writeCode.

IBUTTON_RW1990V1

Indicates RW1990V1 iButton tag type. Returned from detectWritableType, argument to writeCode. This iButton tag type includes models sold as RW1990, RW1990.1, ТМ08 and ТМ08v2.

IBUTTON_RW1990V2

Indicates RW1990V2 iButton tag type. Returned from detectWritableType, argument to writeCode. This iButton tag type includes models sold as RW1990v2 and RW1990.2.

IBUTTON_RW2004

Indicates RW2004 iButton tag type. Returned from detectWritableType, argument to writeCode. This iButton tag type includes models sold as RW2004 and TM2004.

IBUTTON_TM01

Indicates TM01 iButton tag type. Argument to writeCode. Because this iButton tag type is non-detectable, this value is not returned from detectWritableType. This iButton tag type includes models sold as TM01 and TM01C.

IBUTTON_MAXWRITABLE

Indicates the maximum value of an iButton tag type constant. Can be used to determine if a tag type value is in valid range.

Functions

iButtonTag( uint8_t pin )

Constructs an iButtonTag object linked to the supplied pin.

Arguments

type	name	description
uint8_t	pin	Arduino pin number this iButtonTag object should be linked to.

int8_t readCode( iButtonCode code, bool old )

Reads one single iButton identifying code from the OneWire.

When multiple iButtons are connected to the OneWire this function will return an invalid reading because of a checksum failure (return value -2) caused by colliding responses. If there is any possibility multiple iButtons are connected, use readCodes instead.

DS1990 iButton tags can’t be used with multiple tags on a single OneWire data line and require special handling. This function facilitates compatibility with the DS1990 iButton Tags when argument old is set to true. However, this reduces compatibility with other iButton tags: DS1990A, DS1990R and TM1990A will still be handled correctly (they offer backwards compatibility), but other OneWire devices (including iButtons) won’t and may even show unexpected behaviour.

Arguments

type	name	description
iButtonCode	code	Variable to store code read from the OneWire.
bool	old	Setting to true enables compatibility with DS1990 iButton tags. Default value is false.

Returns

value	description
1	Next iButton read succesfully, code array filled with identifying code
0	No more iButtons detected, code array is unchanged
-1	Invalid iButton code read, checksum failed, code array with invalid bytes
-2	Invalid iButton code read, all zeros, code array with invalid bytes

int8_t readCodes()

Starts the search for multiple iButton identifying codes on the OneWire.

Resets the domain to search for iButton identifying codes. This function is needed to start searching for codes again. It’s not really needed the first time, though it’s good practice to always use it before enumerating codes with the nextCode function.

Returns

value	description
1	At least one iButton detected, enumerate with nextCode function
0	No iButton detected

int8_t nextCode( iButtonCode code )

Continues the search for multiple iButton identifying codes on the OneWire.

Start the search for multiple iButton identyfying codes with the readCodes function. The is this function to enumerate all iButton identifying codes on the OneWire.

A return value 0 means searching finished succesfully, but there are no more iButtons on the OneWire. Negative return values indicate a problem during the search (mostly due to movement of the iButton on the reader), but additional calls to the function may yield new iButton identifying codes. However, the overall result will be unreliable.

Arguments

type	name	description
iButtonCode	code	Variable to store code read from the OneWire.

Returns

value	description
1	Next iButton read succesfully, code array filled with identifying code
0	No more iButtons detected, code array is unchanged
-1	Invalid iButton code read, checksum failed, code array with invalid bytes
-2	Invalid iButton code read, all zeros, code array with invalid bytes

static int8_t testCode( iButtonCode code )

Tests iButtonCode for validity.

Arguments

type	name	description
iButtonCode	code	Code to be tested.

Returns

value	description
1	iButton code valid
-1	iButton code invalid, checksum failed
-2	iButton code invalid, all zeros

static bool equalCode( iButtonCode a, iButtonCode b )

Tests if two iButtonCode’s are equal.

Arguments

type	name	description
iButtonCode	a	First code to be tested.
iButtonCode	b	Second code to be tested.

Returns

value	description
true	The two iButtonCode’s are equal
false	The two iButtonCode’s are not equal

static void printCode( iButtonCode code, bool reverse )

Prints iButtonCode to Serial as hexadecimal byte values.

Serial must be initialised in the main code first. By default the bytes are printed as received from the iButton (reverse = false). The order can be reversed (reverse = true) to match the sequence fysically engraved on many iButtons.

Arguments

type	name	description
iButtonCode	code	The code to be printed.
bool	reverse	Setting to true will reverse the printed code. Default value is false.

static void updateChecksum( iButtonCode code )

Updates checksum of iButtonCode to a correct value.

Arguments

type	name	description
iButtonCode	code	The code to be updated.

int8_t detectWritableType()

Detects type of (re)writable iButton tag.

Performs multiple tests to check for known reponses of (re)writable iButton tag types. If a detectable (re)writable type is found, the return value indicates the specific model. All supported (re)writable types are defined as iButton (re)writable tag type constants, like IBUTTON_RW1990V1, IBUTTON_RW1990V2, IBUTTON_RW2004 or IBUTTON_TM01.

A return value of iButton (re)writable type constant IBUTTON_UNKNOWN may indicate one of the following:

• iButton tag is not a (re)writable tag. However, it is readable.
• iButton tag is not of a (re)writable type supported by this library. However, it is readable.
• iButton tag is of a (re)writable type supported by this library. However, this specific type is not detectable, like types indicated by IBUTTON_TM01.

Returns

value	description
>0	iButton writable type found as indicated by type constant
0	iButton writable type unknown, no detectable writable type found
-1	No iButton detected

int8_t writeCode( iButtonCode code, int8_t type, bool check )

Writes a new iButton identifying code to a (re)writable tag.

Strong recommendations, please read carefully:

• It is recommended to have only one iButton probe/tag connected to the data line when writing. Some iButton (re)writable tag types will allow multiple tags to be written at the same time, but it may lead to failure.
• It is also recommended to only supply the new code as an argument. The function will try to detect a (re)writable iButton tag type. If it fails, you should seriously check if the tag really is a (re)writable tag of a type supported by this library. As iButton tag type TM01 is non-detectable, this type will never be detected. In this case supply iButton (re)writable tag type constant IBUTTON_TM01. To override auto-detection in other cases, you can also supply an iButton (re)writable tag type constant.
• It is also recommended to have checking on like the default, making sure as much checks as possible are done before actually writing a new code to the iButton tag. As some writeble tags are just write once there is a risk in trying to write without appropriate checking.

This function supports writing a new iButton identification code to tag models RW1990, RW1990.1, ТM08, ТM08v2 (type IBUTTON_RW1990V1), RW1990v2, RW1990.2 (type IBUTTON_RW1990V2), RW2004, TM2004 (type IBUTTON_RW2004), TM01 and TM01C (type IBUTTON_TM01).

Arguments

type	name	description
iButtonCode	code	Code to be written.
int8_t	type	iButton (re)writable tag type, use library constants. Default value is IBUTTON_UNKNOWN.
bool	check	Setting to false disables most checking done before trying to write. Default value is true.

Returns grouped

value	description
1	Writing procedure finished successfully
0	No iButton detected at some time during procedure
-1 to -9	Problem related to supplied code
-11 to -19	Problem related to supplied type
-21 to -29	Failure of actual writing

Returns specific

value	description
1	Writing procedure finished successfully
0	No iButton detected at some time during procedure
-1	iButton code invalid, checksum failed
-2	iButton code invalid, all zeros
-11	iButton writable type invalid, supplied value out of range
-12	iButton writable type not detectable, supply specific type constant
-13	iButton writable type incorrect, unexpected response while testing
-21	Writing code failed, code read after writing procedure is not equal
-22	Writing code failed, unexpected response while writing