Logging tweaks. Added resolution end inclusive/exclusive methods to

RangeUtil.

diozero-bom/pom.xml

@@ -67,7 +67,7 @@
 		<maven-javadoc-plugin.version>3.6.3</maven-javadoc-plugin.version>
 		<maven-jar-plugin.version>3.3.0</maven-jar-plugin.version>
 		<maven-shade-plugin.version>3.5.2</maven-shade-plugin.version>
-		<maven-source-plugin.version>3.3.0</maven-source-plugin.version>
+		<maven-source-plugin.version>3.3.1</maven-source-plugin.version>
 		<maven-install-plugin.version>3.1.1</maven-install-plugin.version>
 		<maven-deploy-plugin.version>3.1.1</maven-deploy-plugin.version>
 		<maven-gpg-plugin.version>3.2.2</maven-gpg-plugin.version>
@@ -88,7 +88,7 @@
 		<google-gson.version>2.10.1</google-gson.version>
 		<google-protobuf-java.version>3.25.2</google-protobuf-java.version>
 		<netty.version>4.1.108.Final</netty.version>
-		<grpc.version>1.62.2</grpc.version>
+		<grpc.version>1.63.0</grpc.version>
 		<junit.version>5.10.2</junit.version>
 		<mockito.version>5.11.0</mockito.version>
 	</properties>

diozero-core/src/main/java/com/diozero/api/AnalogInputDevice.java

@@ -44,11 +44,10 @@
 
 /**
  * <p>
- * The AnalogInputDevice base class encapsulates logic for interfacing with
- * analog devices. This class provides access to unscaled (-1..1) and scaled
- * (e.g. voltage, temperature, distance) readings. For scaled readings is
- * important that the device factory is configured correctly - all raw analog
- * readings are normalised (i.e. -1..1).
+ * The AnalogInputDevice base class encapsulates logic for interfacing with analog
+ * devices. This class provides access to unscaled (-1..1) and scaled (e.g. voltage,
+ * temperature, distance) readings. For scaled readings is important that the device
+ * factory is configured correctly - all raw analog readings are normalised (i.e. -1..1).
  * </p>
  * <p>
  * Note: The Raspberry Pi does not natively support analog input devices, see
@@ -69,7 +68,7 @@
  * try (McpAdc adc = new McpAdc(type, chipSelect); TMP36 tmp36 = new TMP36(adc, pin, vRef, tempOffset)) {
  * 	for (int i = 0; i < ITERATIONS; i++) {
  * 		double tmp = tmp36.getTemperature();
- * 		Logger.info("Temperature: {}", String.format("%.2f", Double.valueOf(tmp)));
+ * 		Logger.info("Temperature: {0.##}", Double.valueOf(tmp));
  * 		SleepUtil.sleepSeconds(.5);
  * 	}
  * }
@@ -225,8 +224,7 @@ public float getRange() {
 	}
 
 	/**
-	 * Get the unscaled normalised value in the range 0..1 (if unsigned) or -1..1
-	 * (if signed)
+	 * Get the unscaled normalised value in the range 0..1 (if unsigned) or -1..1 (if signed)
 	 * 
 	 * @return the unscaled value
 	 * @throws RuntimeIOException if there was an I/O error
@@ -236,8 +234,7 @@ public float getUnscaledValue() throws RuntimeIOException {
 	}
 
 	/**
-	 * Get the scaled value in the range 0..range (if unsigned) or -range..range (if
-	 * signed)
+	 * Get the scaled value in the range 0..range (if unsigned) or -range..range (if signed)
 	 * 
 	 * @return the scaled value (-range..range)
 	 * @throws RuntimeIOException if there was an I/O error

diozero-core/src/main/java/com/diozero/devices/sandpit/HCSR04UsingWait.java

@@ -46,13 +46,12 @@
  * https://docs.google.com/document/d/1Y-yZnNhMYy7rwhAgyL_pfa39RsB-x2qR4vP8saG73rE/edit#
  * Product specification: http://www.micropik.com/PDF/HCSR04.pdf
  *
- * Provides 2cm - 400cm non-contact measurement function, the ranging accuracy
- * can reach to 3mm You only need to supply a short 10uS pulse to the trigger
- * input to start the ranging, and then the module will send out an 8 cycle
- * burst of ultrasound at 40 kHz and raise its echo. The Echo is a distance
- * object that is pulse width and the range in proportion. We suggest to use
- * over 60ms measurement cycle, in order to prevent trigger signal to the echo
- * signal
+ * Provides 2cm - 400cm non-contact measurement function, the ranging accuracy can reach
+ * to 3mm You only need to supply a short 10uS pulse to the trigger input to start the
+ * ranging, and then the module will send out an 8 cycle burst of ultrasound at 40 kHz and
+ * raise its echo. The Echo is a distance object that is pulse width and the range in
+ * proportion. We suggest to use over 60ms measurement cycle, in order to prevent trigger
+ * signal to the echo signal
  */
 public class HCSR04UsingWait implements DistanceSensorInterface {
 	public static void main(String[] args) {
@@ -65,7 +64,7 @@ public static void main(String[] args) {
 
 		try (HCSR04UsingWait device = new HCSR04UsingWait(trigger_pin, echo_pin)) {
 			while (true) {
-				Logger.info("Distance = {} cm", String.format("%.3f", Double.valueOf(device.getDistanceCm())));
+				Logger.info("Distance = {0.###} cm", Double.valueOf(device.getDistanceCm()));
 				SleepUtil.sleepMillis(1000);
 			}
 		} catch (RuntimeIOException ex) {

diozero-core/src/main/java/com/diozero/internal/soc/rockchip/RK3288MmapGpio.java

@@ -128,8 +128,8 @@ public synchronized void initialise() {
 		if (gpioBanks == null) {
 			gpioBanks = new MmapIntBuffer[9];
 			for (int i = 0; i < gpioBanks.length; i++) {
-				gpioBanks[i] = new MmapIntBuffer(GPIOMEM_DEVICE, GPIO_BASE + i * GPIO_LENGTH + (i > 0 ? GPIO_CHANNEL : 0),
-						PAGE_SIZE, ByteOrder.LITTLE_ENDIAN);
+				gpioBanks[i] = new MmapIntBuffer(GPIOMEM_DEVICE,
+						GPIO_BASE + i * GPIO_LENGTH + (i > 0 ? GPIO_CHANNEL : 0), PAGE_SIZE, ByteOrder.LITTLE_ENDIAN);
 			}
 			pmuMmapIntBuffer = new MmapIntBuffer(GPIOMEM_DEVICE, PMU_BASE, PAGE_SIZE, ByteOrder.LITTLE_ENDIAN);
 			grfMmapIntBuffer = new MmapIntBuffer(GPIOMEM_DEVICE, GRF_BASE, PAGE_SIZE, ByteOrder.LITTLE_ENDIAN);
@@ -545,8 +545,8 @@ public static void main(String[] args) {
 				}
 				long duration_ns = System.nanoTime() - start_nano;
 
-				Logger.info("Duration for {} iterations: {}s", Integer.valueOf(iterations),
-						String.format("%.4f", Float.valueOf(((float) duration_ns) / 1000 / 1000 / 1000)));
+				Logger.info("Duration for {} iterations: {0.####}s", Integer.valueOf(iterations),
+						Float.valueOf(((float) duration_ns) / 1000 / 1000 / 1000));
 			}
 		}
 	}

diozero-core/src/main/java/com/diozero/util/RangeUtil.java

@@ -32,8 +32,6 @@
  */
 
 public class RangeUtil {
-	private static final boolean DEFAULT_MAP_CONSTRAIN = true;
-
 	public static int constrain(int value, int min, int max) {
 		return Math.min(max, Math.max(value, min));
 	}
@@ -47,8 +45,68 @@ public static double constrain(double value, double min, double max) {
 	}
 
 	/**
-	 * Map a number from one range to another. Based on Arduino's map(). Example:
-	 * <code>RangeUtil.map(500, 0, 1000, 0, 255);</code>
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Assumes both ranges start at 0. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(500, 1000, 256);</code> returns 128.
+	 *
+	 * @param value    value to map
+	 * @param fromHigh high end of originating range
+	 * @param toHigh   high end of target range
+	 * @return mapped value
+	 */
+	public static int map(int value, int fromHigh, int toHigh) {
+		return map(value, 0, fromHigh, 0, toHigh, true);
+	}
+
+	/**
+	 * Map a number from one range to another. Assumes both ranges start at 0. Based on
+	 * Arduino's map(). Example: <code>RangeUtil.map(1500, 1000, 256, false);</code> returns
+	 * 384 (128+256).
+	 *
+	 * @param value     value to map
+	 * @param fromHigh  high end of originating range
+	 * @param toHigh    high end of target range
+	 * @param constrain whether to constrain the returned value to the specified range
+	 * @return mapped value
+	 */
+	public static int map(int value, int fromHigh, int toHigh, boolean constrain) {
+		return map(value, 0, fromHigh, 0, toHigh, constrain);
+	}
+
+	/**
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(0, -1000, 1000, 0, 256);</code> returns 128.
+	 *
+	 * @param value    value to map
+	 * @param fromLow  low end of originating range
+	 * @param fromHigh high end of originating range
+	 * @param toLow    low end of target range
+	 * @param toHigh   high end of target range
+	 * @return mapped value
+	 */
+	public static int map(int value, int fromLow, int fromHigh, int toLow, int toHigh) {
+		return map(value, fromLow, fromHigh, toLow, toHigh, true);
+	}
+
+	/**
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Assumes both ranges start at 0. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(0.5f, 1f, 256);</code> returns 128.
+	 *
+	 * @param value    value to map
+	 * @param fromHigh high end of originating range
+	 * @param toHigh   high end of target range
+	 * @return mapped value
+	 */
+	public static int map(float value, float fromHigh, int toHigh) {
+		return map(value, 0, fromHigh, 0, toHigh, true);
+	}
+
+	/**
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(1.5f, 1f, 2f, 0, 256);</code> returns 128.
 	 *
 	 * @param value    value to map
 	 * @param fromLow  low end of originating range
@@ -58,20 +116,19 @@ public static double constrain(double value, double min, double max) {
 	 * @return mapped value
 	 */
 	public static int map(float value, float fromLow, float fromHigh, int toLow, int toHigh) {
-		return map(value, fromLow, fromHigh, toLow, toHigh, DEFAULT_MAP_CONSTRAIN);
+		return map(value, fromLow, fromHigh, toLow, toHigh, true);
 	}
 
 	/**
 	 * Map a number from one range to another. Based on Arduino's map(). Example:
-	 * <code>RangeUtil.map(500, 0, 1000, 0, 255, true);</code>
+	 * <code>RangeUtil.map(0.5f, 1f, 2f, 0, 256, false);</code> returns -128.
 	 *
 	 * @param value     value to map
 	 * @param fromLow   low end of originating range
 	 * @param fromHigh  high end of originating range
 	 * @param toLow     low end of target range
 	 * @param toHigh    high end of target range
-	 * @param constrain whether to constrain the returned value to the speceified
-	 *                  range
+	 * @param constrain whether to constrain the returned value to the specified range
 	 * @return mapped value
 	 */
 	public static int map(float value, float fromLow, float fromHigh, int toLow, int toHigh, boolean constrain) {
@@ -83,8 +140,23 @@ public static int map(float value, float fromLow, float fromHigh, int toLow, int
 	}
 
 	/**
-	 * Map a number from one range to another. Based on Arduino's map(). Example:
-	 * <code>RangeUtil.map(500, 0, 1000, 0, 255);</code>
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Assumes both ranges start at zero. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(0.5f, 1f, 256f);</code> returns 128f.
+	 *
+	 * @param value    value to map
+	 * @param fromHigh high end of originating range
+	 * @param toHigh   high end of target range
+	 * @return mapped value
+	 */
+	public static float map(float value, float fromHigh, float toHigh) {
+		return map(value, 0, fromHigh, 0, toHigh, true);
+	}
+
+	/**
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(1.5f, 1f, 2f, 0f, 256f);</code> returns 128f.
 	 *
 	 * @param value    value to map
 	 * @param fromLow  low end of originating range
@@ -94,20 +166,19 @@ public static int map(float value, float fromLow, float fromHigh, int toLow, int
 	 * @return mapped value
 	 */
 	public static float map(float value, float fromLow, float fromHigh, float toLow, float toHigh) {
-		return map(value, fromLow, fromHigh, toLow, toHigh, DEFAULT_MAP_CONSTRAIN);
+		return map(value, fromLow, fromHigh, toLow, toHigh, true);
 	}
 
 	/**
 	 * Map a number from one range to another. Based on Arduino's map(). Example:
-	 * <code>RangeUtil.map(500, 0, 1000, 0, 255);</code>
+	 * <code>RangeUtil.map(500, 0, 1000, 0, 256);</code> returns 128.
 	 *
 	 * @param value     value to map
 	 * @param fromLow   low end of originating range
 	 * @param fromHigh  high end of originating range
 	 * @param toLow     low end of target range
 	 * @param toHigh    high end of target range
-	 * @param constrain whether to constrain the returned value to the speceified
-	 *                  range
+	 * @param constrain whether to constrain the returned value to the specified range
 	 * @return mapped value
 	 */
 	public static float map(float value, float fromLow, float fromHigh, float toLow, float toHigh, boolean constrain) {
@@ -119,8 +190,23 @@ public static float map(float value, float fromLow, float fromHigh, float toLow,
 	}
 
 	/**
-	 * Map a number from one range to another. Based on Arduino's map(). Example:
-	 * <code>RangeUtil.map(500, 0, 1000, 0, 255);</code>
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Assumes both ranges start at zero. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(500, 1000, 256);</code> returns 128
+	 *
+	 * @param value    value to map
+	 * @param fromHigh high end of originating range
+	 * @param toHigh   high end of target range
+	 * @return mapped value
+	 */
+	public static double map(double value, double fromHigh, double toHigh) {
+		return map(value, 0, fromHigh, 0, toHigh, true);
+	}
+
+	/**
+	 * Map a number from one range to another and constrain the resulting value to be within
+	 * the target range. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(500, 0, 1000, 0, 256);</code> returns 128.
 	 *
 	 * @param value    value to map
 	 * @param fromLow  low end of originating range
@@ -130,9 +216,21 @@ public static float map(float value, float fromLow, float fromHigh, float toLow,
 	 * @return mapped value
 	 */
 	public static double map(double value, double fromLow, double fromHigh, double toLow, double toHigh) {
-		return map(value, fromLow, fromHigh, toLow, toHigh, DEFAULT_MAP_CONSTRAIN);
+		return map(value, fromLow, fromHigh, toLow, toHigh, true);
 	}
 
+	/**
+	 * Map a number from one range to another. Based on Arduino's map(). Example:
+	 * <code>RangeUtil.map(500, 0, 1000, 0, 256);</code> returns 128.
+	 *
+	 * @param value     value to map
+	 * @param fromLow   low end of originating range
+	 * @param fromHigh  high end of originating range
+	 * @param toLow     low end of target range
+	 * @param toHigh    high end of target range
+	 * @param constrain whether to constrain the returned value to the specified range
+	 * @return mapped value
+	 */
 	public static double map(double value, double fromLow, double fromHigh, double toLow, double toHigh,
 			boolean constrain) {
 		double result = (value - fromLow) * (toHigh - toLow) / (fromHigh - fromLow) + toLow;
@@ -141,4 +239,12 @@ public static double map(double value, double fromLow, double fromHigh, double t
 		}
 		return result;
 	}
+
+	public static int resolutionEndInclusive(int numBits) {
+		return 1 << numBits;
+	}
+
+	public static int resolutionEndExclusive(int numBits) {
+		return resolutionEndInclusive(numBits) - 1;
+	}
 }

diozero-core/src/test/java/com/diozero/devices/McpAdcTest.java

@@ -52,7 +52,7 @@ public abstract class McpAdcTest {
 	public static void beforeAll() {
 		TestDeviceFactory.setSpiDeviceClass(TestMcpAdcSpiDevice.class);
 	}
-	
+
 	public McpAdcTest(McpAdc.Type type) {
 		this.type = type;
 	}
@@ -62,7 +62,7 @@ public void setup() {
 		Logger.info("setup(), type=" + type);
 		TestMcpAdcSpiDevice.setType(type);
 	}
-	
+
 	@Test
 	public void test() {
 		int spi_chip_select = 0;
@@ -72,31 +72,31 @@ public void test() {
 
 		try (McpAdc adc = new McpAdc(type, spi_chip_select, voltage);
 				AnalogInputDevice device = new AnalogInputDevice(adc, pin_number)) {
-			for (int i=0; i<iterations; i++) {
+			for (int i = 0; i < iterations; i++) {
 				float unscaled_val = adc.getValue(pin_number);
-				Logger.info("Value: {}", String.format("%.2f", Float.valueOf(unscaled_val)));
+				Logger.info("Value: {0.##}", Float.valueOf(unscaled_val));
 				if (type.isSigned()) {
 					Assertions.assertTrue(unscaled_val >= -1 && unscaled_val < 1, "Unscaled range");
 				} else {
 					Assertions.assertTrue(unscaled_val >= 0 && unscaled_val < 1, "Unscaled range");
 				}
-				
+
 				unscaled_val = device.getUnscaledValue();
-				Logger.info("Unscaled value: {}", String.format("%.2f", Float.valueOf(unscaled_val)));
+				Logger.info("Unscaled value: {0.##}", Float.valueOf(unscaled_val));
 				if (type.isSigned()) {
 					Assertions.assertTrue(unscaled_val >= -1 && unscaled_val < 1, "Unscaled range");
 				} else {
 					Assertions.assertTrue(unscaled_val >= 0 && unscaled_val < 1, "Unscaled range");
 				}
-				
+
 				float scaled_val = device.getScaledValue();
-				Logger.info("Scaled value: {}", String.format("%.2f", Float.valueOf(scaled_val)));
+				Logger.info("Scaled value: {0.##}", Float.valueOf(scaled_val));
 				if (type.isSigned()) {
 					Assertions.assertTrue(scaled_val >= -voltage && scaled_val < voltage, "Scaled range");
 				} else {
 					Assertions.assertTrue(scaled_val >= 0 && scaled_val < voltage, "Scaled range");
 				}
-				
+
 				SleepUtil.sleepMillis(100);
 			}
 		}