0.1.0 DS2401

RobTillaart · Dec 31, 2023 · b3543da · b3543da
1 parent 41cc694
commit b3543da
Show file tree

Hide file tree

Showing 15 changed files with 572 additions and 0 deletions.
diff --git a/libraries/DS2401/.arduino-ci.yml b/libraries/DS2401/.arduino-ci.yml
@@ -0,0 +1,36 @@
+platforms:
+  rpipico:
+    board: rp2040:rp2040:rpipico
+    package: rp2040:rp2040
+    gcc:
+      features:
+      defines:
+        - ARDUINO_ARCH_RP2040
+      warnings:
+      flags:
+
+packages:
+  rp2040:rp2040:
+    url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+
+compile:
+  # Choosing to run compilation tests on 2 different Arduino platforms
+  platforms:
+    - uno
+    # - due
+    # - zero
+    # - leonardo
+    - m4
+    # - esp32     //  pretty strict compiler
+    - esp8266
+    # - mega2560
+    - rpipico
+  # Declaring Dependent Arduino Libraries (to be installed via the Arduino Library Manager)
+  libraries:
+    - "OneWire"
+
+unittest:
+  # These dependent libraries will be installed
+  libraries:
+    - "OneWire"
+    - "util/crc16"
diff --git a/libraries/DS2401/.github/FUNDING.yml b/libraries/DS2401/.github/FUNDING.yml
@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: RobTillaart
+
diff --git a/libraries/DS2401/.github/workflows/arduino-lint.yml b/libraries/DS2401/.github/workflows/arduino-lint.yml
@@ -0,0 +1,13 @@
+
+name: Arduino-lint
+
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: arduino/arduino-lint-action@v1
+        with:
+          library-manager: update
+          compliance: strict
diff --git a/libraries/DS2401/.github/workflows/arduino_test_runner.yml b/libraries/DS2401/.github/workflows/arduino_test_runner.yml
@@ -0,0 +1,17 @@
+---
+name: Arduino CI
+
+on: [push, pull_request]
+
+jobs:
+  runTest:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - run: |
+          gem install arduino_ci
+          arduino_ci.rb
diff --git a/libraries/DS2401/.github/workflows/jsoncheck.yml b/libraries/DS2401/.github/workflows/jsoncheck.yml
@@ -0,0 +1,18 @@
+name: JSON check
+
+on:
+  push:
+    paths:
+      - '**.json'
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: json-syntax-check
+        uses: limitusus/json-syntax-check@v1
+        with:
+          pattern: "\\.json$"
+
diff --git a/libraries/DS2401/CHANGELOG.md b/libraries/DS2401/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Change Log DS2401
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [0.1.0] - 2023-12-31
+- initial version
+
+
+
diff --git a/libraries/DS2401/DS2401.h b/libraries/DS2401/DS2401.h
@@ -0,0 +1,59 @@
+#pragma once
+//
+//    FILE: DS2401.h
+//  AUTHOR: Rob Tillaart
+// PURPOSE: Library for the DS2401 1-wire unique identification chip.
+// VERSION: 0.1.0
+//     URL: https://github.com/RobTillaart/DS2401
+
+
+#include "Arduino.h"
+#include "OneWire.h"
+
+
+#define DS2401_LIB_VERSION            (F("0.1.0"))
+
+
+class DS2401
+{
+public:
+  explicit DS2401(OneWire * ow)
+  {
+    _oneWire = ow;
+  }
+
+  bool begin()
+  {
+    //  reset address
+    for (int i = 0; i < 8; i++)
+    {
+      _address[i] = 0x00;
+    }
+
+    _oneWire->reset();
+    _oneWire->reset_search();
+    _oneWire->search(_address);
+    //  ds2401 has an family ID of 0x01 but this way 
+    //  all one-wire devices can be used as UID.
+    return (_address[0] != 0x00) && (_oneWire->crc8(_address, 7) == _address[7]);
+  }
+
+  void getUID(uint8_t * buffer)
+  {
+    memcpy(buffer, _address, 8);
+  }
+
+  bool compareUID(uint8_t * buffer)
+  {
+    return memcmp(buffer, _address, 8);
+  }
+
+
+private:
+  OneWire * _oneWire;
+  uint8_t   _address[8];
+};
+
+
+//  -- END OF FILE --
+
diff --git a/libraries/DS2401/LICENSE b/libraries/DS2401/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2023 Rob Tillaart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/libraries/DS2401/README.md b/libraries/DS2401/README.md
@@ -0,0 +1,129 @@
+
+[![Arduino CI](https://github.com/RobTillaart/DS2401/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![Arduino-lint](https://github.com/RobTillaart/DS2401/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/DS2401/actions/workflows/arduino-lint.yml)
+[![JSON check](https://github.com/RobTillaart/DS2401/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/DS2401/actions/workflows/jsoncheck.yml)
+[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/DS2401.svg)](https://github.com/RobTillaart/DS2401/issues)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/DS2401/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/DS2401.svg?maxAge=3600)](https://github.com/RobTillaart/DS2401/releases)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/DS2401.svg)](https://registry.platformio.org/libraries/robtillaart/DS2401)
+
+
+# DS2401
+
+Library for the DS2401 1-wire unique identification chip.
+
+
+## Description
+
+The DS2401 is an ID chip that uses the oneWire (1-Wire) protocol. 
+In fact it just returns its address as these are (quite) unique.
+
+Every oneWire device has a unique 48 bit number which together with
+the device family byte and an 8 bits CRC forms 8 byte unique code.
+The family byte adds to the uniqueness however the CRC does not.
+Although the CRC does not add to the uniqueness, it is taken into
+the UID as it allows to check the other 7 bytes for integrity.
+
+As there are at least 8 device types / families known, there are 
+thus at least 51 bits of uniqueness.
+This gives in total more than 10^15 bit patterns, which should be 
+sufficient for most applications.
+
+The library is meant for DS2401 chips but allows all oneWire devices
+to be used as an unique ID (UID). This implies that functionality
+like e.g. temperature sensing is not available with this library.
+
+Known family bytes, there are many other 1-Wire devices with unknown family.
+
+|  byte  |  device    |  description  |
+|:------:|:----------:|:--------------|
+|  0x01  |  DS2401    |  UID device
+|  0x26  |  DS2438    |  Battery monitor
+|  0x2D  |  DS2807    |  EEPROM
+|  0x22  |  DS1822    |  thermometer
+|  0x3B  |  DS1825    |  thermometer
+|  0x28  |  DS18B20   |  thermometer
+|  0x10  |  DS18S20   |  thermometer
+|  0x42  |  DS28EA00  |  thermometer
+
+
+#### Related
+
+- https://github.com/RobTillaart/DS2401
+- https://github.com/RobTillaart/DS28CM00    (I2C)
+- https://github.com/RobTillaart/UUID
+- https://github.com/RobTillaart/DS18B20_INT
+- https://github.com/RobTillaart/DS18B20_RT
+- https://github.com/milesburton/Arduino-Temperature-Control-Library
+
+
+## Interface
+
+```cpp
+#include "DS2401.h"
+```
+
+#### Core
+
+This DS2401 library supports only one device per pin, and no parasite mode.
+The class supports getting an UID and compare an UID.
+
+- **DS2401(OneWire \* ow)** constructor needs a reference to OneWire object.
+- **bool begin()** resets oneWire and search fot the address. 
+Returns true if address / UID of the device is found. 
+- **void getUID(uint8_t \* buffer)** copies the found UID in **begin()** to buffer.
+- **bool compareUID(uint8_t \* buffer)** compares the buffer with the internal UID.
+Returns true if they are identical.
+
+
+## Operation
+
+This library supports only one DS2401 per Arduino / MCU pin.
+
+```
+    //  BOTTOM VIEW
+    //
+    //          PIN  MEANING
+    //   /---+
+    //  /  o |  1    GND
+    //  |  o |  2    DATA
+    //  \  o |  3    VCC
+    //   \---+
+```
+(always check datasheet)
+
+Connect a pull-up resistor 4.7 KΩ between pin3 and pin2. 
+When the wires are longer this resistor needs to be smaller.
+
+
+## Future
+
+#### Must
+
+- Improve documentation.
+
+#### Should
+
+- example of compare function.
+- test with different hardware.
+
+#### Could
+
+- performance test. (mainly fetching)
+- use only 48 unique bits instead of all 64? 
+  - add **getUID48()** and **compareUID48()**
+
+#### Wont
+
+- get any subset of the 8 bytes? => user can do this.
+
+
+## Support
+
+If you appreciate my libraries, you can support the development and maintenance.
+Improve the quality of the libraries by providing issues and Pull Requests, or
+donate through PayPal or GitHub sponsors.
+
+Thank you,
+
diff --git a/libraries/DS2401/examples/DS2401-getUID/DS2401-getUID.ino b/libraries/DS2401/examples/DS2401-getUID/DS2401-getUID.ino
@@ -0,0 +1,46 @@
+//
+//    FILE: DS2401_getUID.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: DS2401 lib getUID
+//     URL: https://github.com/RobTillaart/DS2401
+
+#include <OneWire.h>
+#include "DS2401.h"
+
+
+#define ONE_WIRE_BUS          2
+
+OneWire   oneWire(ONE_WIRE_BUS);
+DS2401    ds24(&oneWire);
+
+uint8_t   uid[8];
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("DS2401_LIB_VERSION: ");
+  Serial.println(DS2401_LIB_VERSION);
+
+  Serial.print("\ngetUID: ");
+  ds24.getUID(uid);
+
+  for (int i = 0; i < 8; i++)
+  {
+    if (uid[i] < 0x10) Serial.print(0);
+    Serial.print(uid[i]);
+    Serial.print(" ");
+  }
+  Serial.println();
+
+  Serial.println("\ndone...");
+}
+
+
+void loop()
+{
+}
+
+
+// -- END OF FILE --