OneWireNg

<br>

This is an 1-wire service library, intended as an alternative for the classic OneWire library. The library provides basic 1-wire services (reset, search, touch, read, write, parasite powering) and may serve for further work while interfacing with various 1-wire devices.

Table of Contents

• Features
• Usage
  • ESP-IDF
  • Pico SDK
  • Mbed OS
• Supported platforms
• Overdrive mode
• Parasite powering
• Architecture details
  • OneWireNg
    • Memory allocation caveat
  • OneWireNg_BitBang
  • OneWireNg_PLATFORM
    • RP2040 drivers
      • RP2040 PIO driver controlling many buses
• OneWire compatibility
  • DallasTemperature library
• License

<a name="features"></a>

Features

• All bus activities are performed respecting open-drain character of the 1-wire protocol.

  During normal 1-wire activities, the master MCU GPIO controlling the bus is never set high (providing direct voltage source on the bus) instead the GPIO is switched to the reading mode causing the high state seen on the bus via the pull-up resistor.

• 1-wire touch support.

  The 1-wire touch may substantially simplify complex bus activities consisting of write-read pairs by combining them into a single touch activity. See examples for details.

• Parasite powering support.

  The 1-wire bus may be powered directly by the master MCU GPIO or via a switching transistor controlled by a dedicated MCU GPIO. More details below.

• Search filtering.

  Search algorithm allows efficient filtering basing on a selected set of family codes. Maximum size of the set is configurable by CONFIG_MAX_SEARCH_FILTERS.

• Overdrive (high-speed) mode support.

  The overdrive mode enables speed up the 1-wire communication by a factor of 10. Only limited number of 1-wire devices support this mode (e.g. DS2408, DS2431).

• Dallas temperature sensors drivers.

  Generic Dallas thermometers and MAX31850/MAX31851 drivers for handling Dallas thermometers and thermocouples. See examples for details.

• OneWire compatibility interface.

  The interface allows effortless switch into OneWireNg for projects using OneWire library. See below for details.

• Clear and flexible architecture.

  The code architecture allows fast and easy porting for new Arduino platforms or even usage core part of the library outside the Arduino environment. See below for usage details on ESP-IDF, Pico SDK or Mbed OS based platforms.

<a name="usage"></a>

Usage

Refer to examples directory for usage details for each of the supported frameworks: Arduino, ESP-IDF, Pico SDK and Mbed.

For API specification refer to sources inline documentation (mainly OneWireNg class). For convenience it's possible to generate HTML/LaTeX Doxygen documentation by issuing doxygen from the main library directory. The documentation will be placed in extras/doc.

File src/OneWireNg_Config.h contains parameters configuring the library functionality. See the file for more details.

<a name="usage_idf"></a>

ESP-IDF (incl. ESP8266 RTOS SDK v3)

Preferred way to add OneWireNg as a library for Espressif ESP-IDF framework is to add it as a git submodule located at project's components subdirectory:

git submodule add -- https://github.com/pstolarz/OneWireNg components/OneWireNg

Next checkout specific library VERSION:

cd components/OneWireNg
git checkout VERSION

While added the library shall be configured via ESP-IDF native configuration (see Kconfig for details), which shadows the OneWireNg_Config.h configuration file.

<a name="usage_pico"></a>

Pico SDK

Preferred way to add OneWireNg as a library for Raspberry Pi Pico SDK framework is to add it as a git submodule:

git submodule add -- https://github.com/pstolarz/OneWireNg OneWireNg

Checkout on a specific library VERSION:

cd OneWireNg
git checkout VERSION

Finally add OneWireNg as a library in a Pico SDK project's CMakeLists.txt file as follows:

cmake_minimum_required(VERSION 3.13)
include(pico_sdk_import.cmake)

project(some_project)
pico_sdk_init()

add_executable(some_project)

...

add_subdirectory(OneWireNg)
target_link_libraries(some_project PRIVATE OneWireNg)

pico_add_extra_outputs(some_project)

<a name="usage_mbed"></a>

Mbed OS

NOTE: The library usage for Mbed OS is experimental. The only board used for tests of this framework is NUCLEO-L552ZE-Q.

To add OneWireNg as a library for Mbed framework project use (for specific VERSION):

mbed add https://github.com/pstolarz/OneWireNg#VERSION

While added the library shall be configured via Mbed native configuration (see mbed_lib.json for details), which shadows the OneWireNg_Config.h configuration file.

<a name="supported_plats"></a>

Supported platforms

• Arduino AVR.
  • Platform class: OneWireNg_ArduinoAVR.
  • Tested on Arduino UNO (ATmega328P).
• Arduino megaAVR (recent Microchip AVR architecture).
  • Platform class: OneWireNg_ArduinoMegaAVR.
  • Reported to be working.
• Arduino ESP8266/ESP-IDF.
  • Platform class: OneWireNg_ArduinoIdfESP8266.
  • Tested on WemOS D1.
• Arduino/ESP-IDF ESP32 (classic, S, C, H and P families).
  • Platform class: OneWireNg_ArduinoIdfESP32.
  • Tested on ESP32-WROOM-32, ESP32-S2-WROVER, ESP32-S3-WROOM-1, ESP32-C3-32S-Kit.
• Arduino/Pico SDK RP2040.
  • Platform classes: OneWireNg_PicoRP2040, OneWireNg_PicoRP2040PIO.
  • Tested on Raspberry Pi Pico.
• Arduino/Mbed OS based platforms (incl. Edge, Giga, Nano, Nicla, Portena, RP2040).
  • Platform class: OneWireNg_ArduinoMbedHAL.
  • Tested on Raspberry Pi Pico, Nucleo-144 (L552ZE-Q).
• Arduino STM32.
  • Platform class: OneWireNg_ArduinoSTM32.
  • Tested on Nucleo-144 (L552ZE-Q).
• Arduino SAM.
  • Platform class: OneWireNg_ArduinoSAM.
  • Reported to be working.
• Arduino SAMD/SAMD-Beta.
  • Platform class: OneWireNg_ArduinoSAMD.
  • Not tested.

NOTE: Expect more platforms support in the future. I'm inviting all developers eager to help me with porting and testing the library for new platforms.

<a name="od_mode"></a>

Overdrive mode

When configured with CONFIG_OVERDRIVE_ENABLED the library supports 1-wire overdrive mode. The mode requires very strict and short timings while bit-banging data on the 1-wire bus, therefore is vulnerable for any inaccuracies.

While configured with CONFIG_BITBANG_DELAY_CCOUNT the mode is confirmed to work on the following platforms and CPU frequencies:

• AVR
  • Arduino UNO (ATmega328P); 16MHz.
• ESP8266
  • WemOS D1; 160,80MHz.
• ESP32
  • ESP32-WROOM-32; 240,160,80,40,20MHz
  • ESP32-S2-WROVER; 240,160,80,40,20,10MHz
  • ESP32-S3-WROOM-1; 240,160,80MHz (other freqs not tested)
  • ESP32-C3-32S-Kit; 240,160MHz (other freqs not tested)
• RP2040
  • Raspberry Pi Pico; 50-250MHz (bit-banging and PIO drivers)
• STM32
  • NUCLEO-L552ZE-Q; 110MHz

<a name="parasite"></a>

Parasite powering

Bit-banging drivers

For bit-banging type of drivers, the library supports two modes of providing a direct voltage source on the 1-wire bus for parasitically powered slaves:

1. If platform's GPIO set to the high-state (in the output mode) is able to serve as a voltage source, the library may leverage this trait. The master MCU GPIO controlling the 1-wire bus is set to the high-state powering the bus when additional energy is needed for connected slaves.

2. If platform's GPIO is of an open-drain type, then a GPIO is not able to directly serve as a voltage source powering the connected slaves. In this case an additional switching transistor is leveraged to control providing an external power source to the bus and is controlled by a dedicated power-control-GPIO as presented on the following figure.