GEX protocol documentation

UNIT_1WIRE.md 2.7KB

1-Wire

1-Wire is a Dallas (now Maxim) proprietary protocol used by the ubiquitous DS18x20 (DS1820, DS18S20, DS18B20), iButton (contact access chips) and other devices.

The bus uses two wires, Data and GND. A third, Vdd wire, is optional and can be left out for parasitic power from the Data line. See the DS18x20 datasheet for more details.

1-Wire requires precise timing and is implemented by bit-banging in GEX. GEX also implements the Search algorithm for finding all devices connected to the bus. Each device has a unique address, which are found using a form of binary search with hardware support in the individual devices.

The search algorithm is available in a separate repository for easier re-use in other projects: MightyPork/1wire-search.

Commands

CHECK_PRESENCE (0)

Test if there are any devices attached to the bus.

Response:

  • u8 - presence detected (0,1)

SEARCH_ADDR (1)

Start the search algorithm, looking for all devices.

Up to 32 devices can be found in one call. To find more, use the SEARCH_CONTINUE command.

Response:

  • u8 - have more? (0,1) - indicates whether SEARCH_CONTINUE should be used.
  • u64[] - array of 8-byte addresses (litte-endian u64, or arrays of 8 bytes each)

SEARCH_ALARM (2)

Identical to SEARCH_ADDR (see above), except only devices with an active Alarm status are detected. This is used with thermometers which can detect the temperature exceeding pre-selected limits.

SEARCH_CONTINUE (3)

Continue a search (address or alarm). The report format is identical to SEARCH_ADDR, but continues after the last reported address.

READ_ADDR (4)

Read the address of the single device connected to the bus. If more than one device is connected, this will likely fail due to a checksum mismatch.

Response:

  • u64 - a 8-byte addresses (litte-endian u64, or an arrays of 8 bytes)

WRITE (10)

Write bytes to the bus.

Request:

  • u64 - a 8-byte device address
    • 0 = all devices, uses the ROM_SKIP bus command
  • u8[] - bytes to write

READ (11)

Send a query and read bytes from the bus.

Request:

  • u64 - a 8-byte device address
    • 0 = use the ROM_SKIP bus command, use with a single device connected only
  • u16 - read length (bytes)
  • u8 - verify the CRC chekcsum (0,1)
  • u8[] - request bytes (written before reading)

Response:

  • u8[] - read bytes

POLL_FOR_1 (20)

Wait for a READY status (used in DS18x20 measurements).

NOTE: Not available if parasitic power is used, then it just waits the maximal measurement time of DS1820.

A response is issued after all devices are done measuring, or a timeout error is returned.

Events

No events defined for this unit type.