🏠 vdwulp.github.io

📚 Arduino iButtonTag Library

🔗 Quick links

Reference documentation

This iButtonTag library reference documentation describes all available types, constants and functions.
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

Constructor iButtonTag

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.

Function readCode

Reads one single iButtonCode from the data line.

When multiple iButtons are connected to the data line 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 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.

Examples Simple and Single show how to use this function.

Arguments

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

Returns type int8_t

value	description
1	Next iButton read successfully, 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

Function readCodes

Starts the search for multiple iButtonCode’s on the data line.

Resets the domain to search for iButtonCode’s. 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.

Example Multiple shows how to use this function in combination with the nextCode function.

Returns type int8_t

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

Function nextCode

Continues the search for multiple iButtonCode’s on the data line.

Start the search for multiple iButton identyfying codes with the readCodes function. The is this function to enumerate all iButtonCode’s on the data line.

A return value 0 means searching finished successfully, but there are no more iButtons on the data line. 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.

Example Multiple shows how to use this function in combination with the readCodes function.

Arguments

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

Returns type int8_t

value	description
1	Next iButton read successfully, 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 function testCode

Tests iButtonCode for validity.

Arguments

type	name	description
iButtonCode	code	Code to be tested.

Returns type int8_t

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

Static function equalCode

Tests if two iButtonCode’s are equal.

Example Match shows how to use this function.

Arguments

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

Returns type bool

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

Static function printCode

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 function updateChecksum

Updates checksum of iButtonCode to the correct value.

Example WriteCode shows how to use this function.

Arguments

type	name	description
iButtonCode	code	The code to be updated.

Function 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 type int8_t

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

Function writeCode

Writes a new iButtonCode 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 iButtonCode 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).

Example WriteCode shows how to use this function.

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 type int8_t - grouped values

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 type int8_t - specific values

value	description
1	Writing procedure finished successfully
0	No iButton detected at some time during procedure
-1	iButton code invalid, checksum failed, update with updateChecksum
-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