Documentation
¶
Overview ¶
Package ibutton decodes Dallas 1-Wire ROM IDs (a.k.a. iButton keys) into a structured view: family code → device-type name, 48-bit serial, and Dallas CRC-8 validation.
Wrap-vs-native judgement ¶
Native. The 1-Wire ROM ID layout is a 64-bit fixed structure published by Maxim/Dallas Semiconductor (Application Note 001) and the Dallas CRC-8 polynomial (0x31 reflected) is a few lines of bit-twiddling. The family-code → device-type mapping is a static lookup table (~50 entries from the public Maxim AN155 / AN1796 series). No vendor SDK, no hardware dependency, no protocol negotiation: pasting the hex bytes printed by a Flipper iButton dump is enough.
What this package covers ¶
- Dallas DS1990A / DS2401 / DS2411 (the canonical "unique ID" iButton — family 0x01) — by far the most common form-factor encountered on intercoms and building-access systems.
- The full Maxim 1-Wire device family (DS18B20 temperature sensors, DS2431 EEPROM, DS2438 battery monitor, DS2408 8-channel switch, etc. — anything that addresses on a Dallas 1-Wire bus shares the same ROM-ID layout).
- Dallas CRC-8 (poly 0x31, init 0x00, reflected, no final XOR) — verifies that the 8 bytes are a well-formed ROM ID rather than a misread frame.
What this package does NOT cover (deliberately out of scope) ¶
- Cyfral / Metakom / DS1996-style memory dumps — those are separate Russian intercom-key protocols with their own bit-layouts and Manchester encodings; future iterations can add `ibutton_cyfral_decode` / `ibutton_metakom_decode` in this package.
- Memory-contents decoding for the DS197x / DS24xx EEPROM and battery-monitor families — only the ROM ID is decoded here; per-device memory pages need device-specific parsers.
- Reading from a live 1-Wire bus — host-side decode only; hardware ops live in internal/flipper (ibutton_read / emulate / write).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dallas ¶
type Dallas struct {
ROMHex string `json:"rom_hex"`
FamilyCode byte `json:"family_code"`
FamilyHex string `json:"family_hex"`
FamilyName string `json:"family_name"`
SerialHex string `json:"serial_hex"`
CRC byte `json:"crc"`
CRCExpected byte `json:"crc_expected"`
CRCValid bool `json:"crc_valid"`
}
Dallas is the decoded view of a Dallas 1-Wire ROM ID.
Field layout matches the on-wire ROM ID transmission order (LSByte first on the bus, but rendered here in the natural left-to-right byte order from the hex input):
FamilyHex : 8-bit family code (byte 0) FamilyName : device-type name from the family-code table SerialHex : 48-bit serial (bytes 1..6, big-endian) CRC : 8-bit CRC byte as captured (byte 7) CRCExpected : 8-bit CRC computed over bytes 0..6 CRCValid : CRC == CRCExpected
func Decode ¶
Decode parses a hex-encoded Dallas 1-Wire ROM ID into a structured Dallas view. Accepts ':', '-', '_', whitespace as separators and a leading '0x' prefix.
The input must decode to exactly 8 bytes (the fixed ROM-ID width). Shorter / longer inputs are rejected with a clear error — Cyfral and Metakom keys have different widths and require different decoders.
func DecodeBytes ¶
DecodeBytes parses a raw 8-byte ROM ID. Exposed so that callers already holding the bytes (e.g. another decoder stage) don't have to round-trip through hex encoding.
func Encode ¶ added in v0.385.0
Encode builds a complete, well-formed 8-byte Dallas 1-Wire ROM ID from a family code and a 48-bit serial, computing the Dallas/Maxim CRC-8 over the first seven bytes — the inverse of Decode. It returns the assembled 8 bytes plus the decoded view (CRCValid always true) for confirmation.
This is what an operator writes to a blank/magic iButton (a clone): pick the family (0x01 DS1990A is the canonical access-control key), supply the 48-bit serial read off the target key, and the CRC byte is filled in so the ROM passes a reader's integrity check. It is the host-side construction step only — actually burning the ROM is a hardware op (ibutton_write in internal/flipper); this transmits nothing, so it is Low risk like the decoder.
Wrap-vs-native judgement ¶
Native, and the exact inverse of the existing Decode path: it reuses the same computeCRC (Maxim AN-27 polynomial 0x31, reflected) so the two are guaranteed consistent. The ROM-ID layout is the public Maxim 1-Wire structure (family byte, 48-bit serial, CRC byte); pure byte assembly, no hardware, no vendor SDK. Correctness is verifiable two ways: round-trip against Decode and the canonical Maxim AN-27 vector (family 0x02, serial 1C B8 01 00 00 00 → CRC 0xA2).
The serial must be exactly 6 bytes (48 bits) in the same natural left-to-right byte order Decode renders in SerialHex.
Source Files