0.1.0 map2bits

libraries/map2bits/.arduino-ci.yml

@@ -0,0 +1,27 @@
+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
+    # - esp8266
+    # - mega2560
+    - rpipico

libraries/map2bits/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: RobTillaart
+

libraries/map2bits/.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

libraries/map2bits/.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

libraries/map2bits/.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$"
+

libraries/map2bits/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log map2bits
+
+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] - 2024-01-02
+- initial version.

libraries/map2bits/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2024 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.

libraries/map2bits/README.md

@@ -0,0 +1,138 @@
+
+[![Arduino CI](https://github.com/RobTillaart/map2bits/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![Arduino-lint](https://github.com/RobTillaart/map2bits/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/map2bits/actions/workflows/arduino-lint.yml)
+[![JSON check](https://github.com/RobTillaart/map2bits/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/map2bits/actions/workflows/jsoncheck.yml)
+[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/map2bits.svg)](https://github.com/RobTillaart/map2bits/issues)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/map2bits/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/map2bits.svg?maxAge=3600)](https://github.com/RobTillaart/map2bits/releases)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/map2bits.svg)](https://registry.platformio.org/libraries/robtillaart/map2bits)
+
+
+# map2bits
+
+Arduino library for mapping a float to a number of bits.
+
+
+## Description
+
+Map2bits is an **experimental** library which can be used to map a float 
+value to a number of HIGH bits in an 32 bits integer..
+The float value can be the result of a calculation or measurement from a 
+sensor, e.g. temperature, humidity, light, distance, direction or pressure. 
+
+**map2bits** is developed to drive a led bar like this one.
+https://www.tinytronics.nl/shop/nl/displays/segmenten/led-bar-10x-rood
+typical in combination with a PCF8575 or a MCP23017.
+These are used for displaying e.g. audio volume, current level, temperature 
+etc in a visual way.
+
+Another application might be to control multiple pumps in a row to pump 
+water from a pit. 
+Depending on the level of the water more pumps need to be switched on.
+
+In short many devices to drive or applications to think of.
+
+As always, feedback is welcome.
+
+
+#### Related
+
+Other mapping libraries
+
+- https://github.com/RobTillaart/FastMap
+- https://github.com/RobTillaart/Gamma
+- https://github.com/RobTillaart/map2bits
+- https://github.com/RobTillaart/map2colour
+- https://github.com/RobTillaart/moduloMap
+- https://github.com/RobTillaart/MultiMap
+
+
+## Interface
+
+```cpp
+#include "map2bits.h"
+```
+
+#### Functions
+
+- **map2bits()** Constructor, defines a default mapping of (0..100 => 10)
+- **uint8_t init(float in_min, float in_max, uint32_t bits)** defines the mapping
+input range and how many bits output should be generated.
+- **uint32_t map(float value)** maps value to an uint32_t with the appropriate 
+number of bits set. These are constrained by the number of bits set in **init()**.
+
+The output of **map()** is a bit mask and can be used to drive e.g. a led bar etc.
+
+
+## Operation
+
+Suppose you have the following code 
+```
+mb.init(0, 100, 10);
+                       //      (binary)
+x = mb.map(64);        //  x =     111111 ==>  6 bits set, interpolated
+x = mb.map(99);        //  x = 1111111111 ==> 10 bits set, interpolated
+x = mb.map(4);         //  x =          0 ==>  0 bits set, interpolated
+x = mb.map(-10);       //  x =          0 ==>  0 bits set, constrained
+x = mb.map(1000);      //  x = 1111111111 ==> 10 bits set, constrained
+```
+
+See examples.
+
+
+## Performance
+
+Indicative performance measured with the **map2bits_performance.ino** example.
+Performance depends on input chosen, platform support of float, and if
+values are constrained (out range) or interpolated (in range)
+
+Note: time in microseconds per call
+Note: UNO at 16 MHz, ESP32 at 240 MHz
+
+|  board  |  map - in range |  map - out range  |  notes  |
+|:-------:|:---------------:|:-----------------:|:--------|
+|  UNO    |  45.35 us       |  22.20 us         |  33% in range, 66% out range
+|  ESP32  |                 |                   |  to do
+
+
+## Future
+
+#### Must
+
+- update documentation
+- test ESP32
+
+#### Should
+
+- extend the idea to applications
+- add examples
+- optimize
+
+#### Could
+
+- test other boards
+- **map2bits64(value)** uint64_t for 33 - 64 bits output
+  - might need printHelpers
+- **map2bitsDouble(value)** Double version (input range + precision)
+- **map2bitsDouble64(value)** Double version (33 - 64 bits output)
+- uint32_t input version
+- map2DAC? 
+  - maps a range to analogWrite()..
+  - separate class. 
+- polarity  0001 <> 1110 ?
+  - ~operator
+- MSB/LSB   0001 <> 1000 ?
+  - reverse from CRC library
+
+
+#### Wont
+
+
+## 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,

libraries/map2bits/examples/map2bits_demo/map2bits_demo.ino

@@ -0,0 +1,45 @@
+//
+//    FILE: map2bits_demo.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: map2bits demo
+//     URL: https://github.com/RobTillaart/map2bits
+
+
+#include "map2bits.h"
+
+map2bits mb;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("MAP2BITS_LIB_VERSION: ");
+  Serial.println(MAP2BITS_LIB_VERSION);
+  Serial.println();
+
+  mb.init(100, 200, 10);
+  for (int i = 0; i < 300; i += 10)
+  {
+    Serial.println(mb.map(i), BIN);
+  }
+  Serial.println();
+
+  mb.init(100, 1000, 32);
+  for (int i = 0; i <= 1000; i += 1)
+  {
+    Serial.println(mb.map(i), BIN);
+  }
+  Serial.println();
+
+  Serial.println("Done...");
+}
+
+
+void loop()
+{
+
+}
+
+
+// -- END OF FILE --

libraries/map2bits/examples/map2bits_performance/map2bits_performance.ino

@@ -0,0 +1,72 @@
+//
+//    FILE: map2bits_performance.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: map2bits demo
+//     URL: https://github.com/RobTillaart/map2bits
+
+
+#include "map2bits.h"
+
+map2bits mb;
+
+volatile uint32_t x = 0;
+
+uint32_t start, stop;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("MAP2BITS_LIB_VERSION: ");
+  Serial.println(MAP2BITS_LIB_VERSION);
+  Serial.println();
+  delay(100);
+
+
+  mb.init(0, 1000, 10);
+  start = micros();
+  for (int i = 0; i < 1000; i++)
+  {
+    x = mb.map(i);
+  }
+  stop = micros();
+  Serial.println("1000 x map (full)");
+  Serial.print("US: ");
+  Serial.print(stop - start);
+  Serial.print("\t");
+  Serial.println((stop - start) / 1000.0);
+  Serial.print("X:  ");
+  Serial.println(x);
+  Serial.println();
+  delay(100);
+
+
+  mb.init(100, 200, 10);
+  start = micros();
+  for (int i = 0; i < 300; i++)
+  {
+    x = mb.map(i);
+  }
+  stop = micros();
+  Serial.println("3 x 100 x map (constrained)");
+  Serial.print("US: ");
+  Serial.print(stop - start);
+  Serial.print("\t");
+  Serial.println((stop - start) / 300.0);
+  Serial.print("X:  ");
+  Serial.println(x);
+  Serial.println();
+  delay(100);
+
+  Serial.println();
+  Serial.println("Done...");
+}
+
+
+void loop()
+{
+
+}
+
+
+// -- END OF FILE --

libraries/map2bits/examples/map2bits_performance/performance_0.1.0.txt

@@ -0,0 +1,17 @@
+
+Arduino UNO 16 MHz
+IDE 1.8.19
+
+libraries\map2bits\examples\map2bits_performance\map2bits_performance.ino
+MAP2BITS_LIB_VERSION: 0.1.0
+
+1000 x map (full)
+US: 45348	45.35
+X:  1023
+
+3 x 100 x map (constrained)
+US: 6660	22.20
+X:  1023
+
+
+Done...

libraries/map2bits/examples/map2bits_plotter/map2bits_plotter.ino

@@ -0,0 +1,42 @@
+//
+//    FILE: map2bits_plotter.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: map2bits demo
+//     URL: https://github.com/RobTillaart/map2bits
+
+
+#include "map2bits.h"
+
+map2bits mb;
+map2bits mb2;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("MAP2BITS_LIB_VERSION: ");
+  Serial.println(MAP2BITS_LIB_VERSION);
+  Serial.println();
+
+  mb.init(100, 1000, 32);
+  mb2.init(0, 100, 32);
+  for (int i = 0; i <= 1000; i += 2)
+  {
+    Serial.print(mb.map(i), DEC);
+    Serial.print("\t");
+    Serial.println(mb2.map(i), DEC);
+  }
+  Serial.println();
+
+  Serial.println("Done...");
+}
+
+
+void loop()
+{
+
+}
+
+
+// -- END OF FILE --

libraries/map2bits/keywords.txt

@@ -0,0 +1,13 @@
+# Syntax Colouring Map For map2bits
+
+# Data types (KEYWORD1)
+map2bits	KEYWORD1
+
+
+# Methods and Functions (KEYWORD2)
+init	KEYWORD2
+map	KEYWORD2
+
+# Constants (LITERAL1)
+MAP2BITS_LIB_VERSION	LITERAL1
+

libraries/map2bits/library.json

@@ -0,0 +1,23 @@
+{
+  "name": "map2bits",
+  "keywords": "",
+  "description": "Arduino library for mapping a float to a number of bits.",
+  "authors":
+  [
+    {
+      "name": "Rob Tillaart",
+      "email": "Rob.Tillaart@gmail.com",
+      "maintainer": true
+    }
+  ],
+  "repository":
+  {
+    "type": "git",
+    "url": "https://github.com/RobTillaart/map2bits.git"
+  },
+  "version": "0.1.0",
+  "license": "MIT",
+  "frameworks": "*",
+  "platforms": "*",
+  "headers": "map2bits.h"
+}

libraries/map2bits/library.properties

@@ -0,0 +1,11 @@
+name=map2bits
+version=0.1.0
+author=Rob Tillaart <rob.tillaart@gmail.com>
+maintainer=Rob Tillaart <rob.tillaart@gmail.com>
+sentence=Arduino library for mapping a float to a number of bits.
+paragraph=
+category=Data Processing
+url=https://github.com/RobTillaart/map2bits
+architectures=*
+includes=map2bits.h
+depends=

libraries/map2bits/map2bits.cpp

@@ -0,0 +1,45 @@
+//
+//    FILE: map2bits.cpp
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+// PURPOSE: Arduino library for mapping a float to a number of bits.
+//     URL: https://github.com/RobTillaart/map2bits
+
+
+#include "map2bits.h"
+
+
+map2bits::map2bits()
+{
+  init(0, 100, 10);
+}
+
+
+bool map2bits::init(float in_min, float in_max, uint8_t size)
+{
+  float _inRange = in_max - in_min;
+  if ((_inRange == 0.0 ) || (size > 32)) return false;
+
+  _outMax = size;
+  _in_min = in_min;
+  _in_max = in_max;
+
+  _factor = _outMax/_inRange;
+  _base = - _in_min * _factor;
+  return true;
+}
+
+
+uint32_t map2bits::map(float value)
+{
+  if (value <= _in_min) return 0;
+  if (value >= _in_max) return (uint32_t(1) << _outMax) - 1;
+
+  uint8_t count = round(_base + value * _factor);
+  uint32_t bits = (uint32_t(1) << count) - 1;
+  return bits;
+}
+
+
+//  -- END OF FILE --
+

libraries/map2bits/map2bits.h

@@ -0,0 +1,32 @@
+#pragma once
+//
+//    FILE: map2bits.h
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+// PURPOSE: Arduino library for mapping a float to a number of bits.
+//     URL: https://github.com/RobTillaart/map2bits
+
+
+#include "Arduino.h"
+
+
+#define MAP2BITS_LIB_VERSION          (F("0.1.0"))
+
+
+class map2bits
+{
+  public:
+    map2bits();
+
+    bool     init(float in_min, float in_max, uint8_t size);
+    uint32_t map(float value);
+
+  protected:
+    uint8_t _outMax;
+    float _in_min, _in_max;
+    float _factor, _base;
+};
+
+
+//  -- END OF FILE --
+

libraries/map2bits/test/unit_test_001.cpp

@@ -0,0 +1,75 @@
+//
+//    FILE: unit_test_001.cpp
+//  AUTHOR: Rob Tillaart
+//    DATE: 2024-02-02
+// PURPOSE: unit tests for the map2bit library
+//          https://github.com/RobTillaart/map2bits
+//          https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md
+//
+
+// supported assertions
+// ----------------------------
+// assertEqual(expected, actual)
+// assertNotEqual(expected, actual)
+// assertLess(expected, actual)
+// assertMore(expected, actual)
+// assertLessOrEqual(expected, actual)
+// assertMoreOrEqual(expected, actual)
+// assertTrue(actual)
+// assertFalse(actual)
+// assertNull(actual)
+
+
+#include <ArduinoUnitTests.h>
+
+
+#include "map2bits.h"
+
+
+unittest_setup()
+{
+  fprintf(stderr, "MAP2BITS_LIB_VERSION: %s\n", (char *) MAP2BITS_LIB_VERSION);
+}
+
+
+unittest_teardown()
+{
+}
+
+
+unittest(test_constructor)
+{
+  map2bits mb;
+  assertTrue(mb.init(0, 100, 10));
+
+  assertEqual(0, mb.map(-10));
+  assertEqual(0, mb.map(0));
+  assertEqual(0, mb.map(4));
+  assertEqual(1, mb.map(5));
+  assertEqual(1, mb.map(14));
+  assertEqual(3, mb.map(15));
+  assertEqual(3, mb.map(24));
+  assertEqual(7, mb.map(25));
+  assertEqual(7, mb.map(34));
+  assertEqual(15, mb.map(35));
+  assertEqual(15, mb.map(44));
+  assertEqual(31, mb.map(45));
+  assertEqual(31, mb.map(54));
+  assertEqual(63, mb.map(55));
+  assertEqual(63, mb.map(64));
+  assertEqual(127, mb.map(65));
+  assertEqual(127, mb.map(74));
+  assertEqual(255, mb.map(75));
+  assertEqual(255, mb.map(84));
+  assertEqual(511, mb.map(85));
+  assertEqual(511, mb.map(94));
+  assertEqual(1023, mb.map(100));
+  assertEqual(1023, mb.map(1000));
+}
+
+
+unittest_main()
+
+
+//  -- END OF FILE --
+