Merge branch 'johnsonb2-master'

Author: dcyoung

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 9/7/2017
+- Updated `README`
+- Updated `keywords.txt`
+- Expanded `ScanPacket` struct into full class
+  - `ScanPacket` is now immutable, and its data is accessed through getter methods
+  - Obtaining a reading now requires a separate boolean variable for the success flag
+  - Angle data is efficiently stored in raw 16-bit fixed point value
+  - Getter methods provide an interface to obtain the angle as a raw value or as a float in degrees
+- Removed unused method `angle_raw_to_deg` from `Sweep.h`

README.md

@@ -3,23 +3,23 @@ Arduino Library for Scanse Sweep LiDAR
 
 # Compatibility
 ### Arduino
-Currently the library has only been tested with an `Arduino Mega 2560`.
+Currently the library has only been tested with an `Arduino Mega 2560`, an `Arduino Mega ADK`, and an `Arduino Micro`.
+
 ### Sweep Firmware
 | sweep firmware | compatibility |
 | :------------: | :-----------: |
 | > v1.4         | untested      |
 | v1.4           | yes           |
 
-The library is designed to support recent Sweep firmware versions. The communication protocol used by the earlier firmwares may not work properly with this library. You can download the latest firmware [here](http://scanse.io/downloads).
+The library is designed to support the most recent Sweep firmware version. The communication protocol used by earlier firmware versions may not work properly with this library. A guide to updating the Sweep's firmware is available [here](https://support.scanse.io/hc/en-us/articles/224557908-Upgrading-Firmware).
 
 # Installation
 Copy the entire `Sweep/` folder to your `.../Arduino/libraries/` directory.
 
 # Use
-
 Checkout the provided `Examples/` directory for 2 full examples.
 
-For best results, you should provide dedicated external 5V power to the Sweep rather than using power from the Arduino. Just be sure to connect the ground from the power source and the arduino. If you are just experimenting, you can run the sweep off the 5V power from the Arduino with the Arduino receiving power over USB. However this has only been tested with an external powered USB hub. It is possible that using a low power USB port (ex: laptop) to power the arduino + sweep  will result in unexpected behavior.
+For best results, you should provide dedicated external 5V power to the Sweep rather than using power from the Arduino. Just be sure to connect the ground from the power source and the arduino. If you are just experimenting, you can run the sweep off the 5V power from the Arduino with the Arduino receiving power over USB. However, it is possible that using a low power USB port (ex: laptop) to power the arduino + sweep will result in unexpected behavior.
 
 ![Alt text](wiring_diagrams/MegaSerialPrinter.png?raw=true "Title")
 
@@ -71,15 +71,16 @@ Data collection:
 bool bSuccess = device.startScanning();
 ...
 
-// Create a scan packet to populate with the sensor reading
-ScanPacket reading;
 // read 10 individual sensor readings
 for (int i = 0; i < 10; i++) {
-    if(device.getReading(reading)) {
-        bool bFirstOfNewScan = reading.bIsSync;
-        float angle = reading.angle;
-        uint16_t range = reading.distance;
-        uint8_t confidence = reading.signalStrength;
+    // Create a scan packet to populate with the sensor reading
+    bool success = false;
+    ScanPacket reading = device.getReading(success);
+    if(success) {
+        bool bFirstOfNewScan = reading.isSync();
+        float angle = reading.getAngleDegrees();
+        uint16_t range = reading.getDistance();
+        uint8_t confidence = reading.getSignalStrength();
 ...
 
 // stop scanning
@@ -90,17 +91,19 @@ bool bSuccess = device.stopScanning();
 
 # API
 
+### Sweep
+
 ```c++
 Sweep(Stream &serial)
 ```
 
 Constructs a sweep device on the provided Stream object.
 
 ```c++
-bool bIsScanning
+bool isScanning()
 ```
 
-True if the device is currently scanning.
+Returns true if the device is currently scanning.
 
 ```c++
 bool startScanning()
@@ -118,22 +121,16 @@ bool stopScanning()
 Signals the sweep device to stop scanning. Will block for ~500ms to flush leftover data stream from the buffer and validate a second response from the sensor.
 
 ```c++
-bool getReading(ScanPacket &reading)
+ScanPacket getReading(bool &success)
 ```
 
 Reads a single sensor reading from the serial buffer. Must be called frequently enough to keep up with the data stream.
 
 ```c++
-struct ScanPacket
-{
-    bool bIsSync;           // 1 -> first reading of new scan, 0 otherwise
-    float angle;            // degrees
-    uint16_t distance;      // cm
-    uint8_t signalStrength; // 0:255, higher is better
-}
+class ScanPacket
 ```
 
-Structure representing a single sensor reading (ranging). ie: a full 360deg scan would be composed of many such readings.
+Class representing a single sensor reading (ranging). ie: a full 360deg scan would be composed of many such readings.
 
 ```c++
 bool getMotorReady()
@@ -158,6 +155,7 @@ Returns the current motor speed setting in HZ
 bool setMotorSpeed(const uint8_t motorSpeedCode[2])
 
 // Available Codes
+MOTOR_SPEED_CODE_0_HZ
 MOTOR_SPEED_CODE_1_HZ
 MOTOR_SPEED_CODE_2_HZ
 MOTOR_SPEED_CODE_3_HZ
@@ -198,5 +196,49 @@ void reset()
 
 Resets the device. Attempting to communicate with the device while it is resetting will cause issues. While the device is booting the LED on the device will blink green. The device is capable of communication when the LED turns from green to blue, although the motor may still be adjusting until the blue LED stops blinking as well.
 
+### ScanPacket
+
+```c++
+ScanPacket(const bool bIsSync, const uint16_t rawAngle, const uint16_t distance, const uint8_t signalStrength)
+```
+
+Constructs a ScanPacket object with the given parameters. The construction of the ScanPacket object for a reading is handled by the Sweep class's getReading() method; you should not need to use this constructor.
+
+```c++
+bool isSync() const
+```
+
+Returns true if this reading was the first reading of a new scan; otherwise, returns false.
+
+```c++
+float getAngleDegrees() const
+```
+
+Returns the angle of this reading as a float, in degrees.
 
+```c++
+uint16_t getAngleRaw() const
+```
+
+Returns the angle of this reading as the raw 16-bit fixed point value. The scaling factor of this value is 16; this means that the angle in degrees is obtained by dividing the raw value by 16.
+
+```c++
+uint16_t getDistance() const
+```
+
+Returns the distance of this reading, in centimeters.
+
+```c++
+uint8_t getSignalStrength() const
+```
+
+Returns the signal strength of this reading as an integer value between 0 and 255. Signal strength can be thought of as a confidence metric. A low value indicates low strength, and a high value indicates high strength. 
+
+> **Note:** The signal strenth value is affected by light conditions, material properties etc. For more information, see the article on the [Theory of Operation](https://support.scanse.io/hc/en-us/articles/115006333327-Theory-of-Operation).
+
+```c++
+float getNormalizedSignalStrength() const
+```
 
+Returns the signal strength of this reading as a float value normalized between 0 and 1. ie: ints [0:255] map to floats [0.0f:1.0f]. 
+> **Note:** this method only normalizes a raw byte value. It does NOT normalize the signal strength of this reading in the context of the min and max signal strengths from all readings in a scan, as the reading class has no knowledge of a scan.

Sweep/Examples/MegaDistanceBlink/MegaDistanceBlink.ino

@@ -66,8 +66,6 @@ const uint8_t STATE_ERROR = 7;
 
 // Create a Sweep device using Serial #1 (RX1 & TX1)
 Sweep device(Serial1);
-// Scan packet struct, used to store info for a single reading
-ScanPacket reading;
 
 uint16_t closestDistanceInSpecifiedFOV = 4000; // the distance (in cm) of the closest object in the specified angular range
 uint16_t interval = 1000;                      // interval at which to blink onboard LED (milliseconds)
@@ -181,22 +179,24 @@ bool verifyCurrentDeviceSettings()
 bool gatherDistanceInfo()
 {
   // attempt to get the next scan packet
-  // Note: getReading() will write values into the "reading" variable
-  if (device.getReading(reading))
+  // Note: getReading() will return a ScanPacket object
+  bool success = false;
+  ScanPacket reading = device.getReading(success);
+  if (success)
   {
     // marks the end of the angular range, so report true
-    if (reading.bIsSync)
+    if (reading.isSync())
       return true;
 
     // consider a Field of View in the angular range [360-FOV: 0]
-    if (reading.angle > 360 - FOV)
+    if (reading.getAngleDegrees() > 360 - FOV)
     {
       // only consider valid readings (sensor will report distance of 1 for failed readings)
-      if (reading.distance > 1)
+      if (reading.getDistance() > 1)
       {
         // check if this reading is closer than anything seen so far
-        if (reading.distance < closestDistanceInSpecifiedFOV)
-          closestDistanceInSpecifiedFOV = reading.distance;
+        if (reading.getDistance() < closestDistanceInSpecifiedFOV)
+          closestDistanceInSpecifiedFOV = reading.getDistance();
       }
     }
   }
@@ -244,4 +244,4 @@ void reset()
   ledState = LOW;
   digitalWrite(LED_BUILTIN, ledState); // turn the LED off by making the voltage LOW
   device.reset();
-}
+}

Sweep/Examples/MegaSerialPrinter/MegaSerialPrinter.ino

@@ -31,8 +31,6 @@
 
 // Create a Sweep device using Serial #1 (RX1 & TX1)
 Sweep device(Serial1);
-// Scan packet struct, used to store info for a single reading
-ScanPacket reading;
 
 // keeps track of how many scans have been collected
 uint8_t scanCount = 0;
@@ -193,21 +191,23 @@ void gatherSensorReading()
 {
   // attempt to get the next scan packet
   // Note: getReading() will write values into the "reading" variable
-  if (device.getReading(reading))
+  bool success = false;
+  ScanPacket reading = device.getReading(success);
+  if (success)
   {
     // check if this reading was the very first reading of a new 360 degree scan
-    if (reading.bIsSync)
+    if (reading.isSync())
       scanCount++;
 
     // don't collect more than 3 scans
     if (scanCount > 3)
       return;
 
     // store the info for this sample
-    syncValues[sampleCount] = reading.bIsSync;
-    angles[sampleCount] = reading.angle;
-    distances[sampleCount] = reading.distance;
-    signalStrengths[sampleCount] = reading.signalStrength;
+    syncValues[sampleCount] = reading.isSync();
+    angles[sampleCount] = reading.getAngleDegrees();
+    distances[sampleCount] = reading.getDistance();
+    signalStrengths[sampleCount] = reading.getSignalStrength();
 
     // increment sample count
     sampleCount++;
@@ -259,4 +259,4 @@ void reset()
   userInput = "";
   Serial.println("\n\nWhenever you are ready, type \"start\" to to begin the sequence...");
   currentState = 0;
-}
+}

Sweep/ScanPacket.cpp

@@ -0,0 +1,36 @@
+#include "ScanPacket.h"
+
+ScanPacket::ScanPacket(const bool bIsSync, const uint16_t rawAngle,
+    const uint16_t distance, const uint8_t signalStrength):
+    _bIsSync(bIsSync), _rawAngle(rawAngle), _distance(distance),
+    _signalStrength(signalStrength) {}
+
+bool ScanPacket::isSync() const
+{
+    return _bIsSync;
+}
+
+float ScanPacket::getAngleDegrees() const
+{
+    return _rawAngle / SCALING_FACTOR;
+}
+
+uint16_t ScanPacket::getAngleRaw() const
+{
+    return _rawAngle;
+}
+
+uint16_t ScanPacket::getDistance() const
+{
+    return _distance;
+}
+
+uint8_t ScanPacket::getSignalStrength() const
+{
+    return _signalStrength;
+}
+
+float ScanPacket::getNormalizedSignalStrength() const
+{
+    return _signalStrength / 255;
+}

Sweep/ScanPacket.h

@@ -0,0 +1,44 @@
+#ifndef _SCANPACKET_H
+#define _SCANPACKET_H
+
+#include <stdint.h>
+
+/**
+*   Class representing the data block returned from the Sweep.
+*/
+class ScanPacket
+{
+  public:
+    // Constructor
+    ScanPacket(const bool bIsSync, const uint16_t rawAngle,
+        const uint16_t distance, const uint8_t signalStrength);
+
+    // Returns true if this reading is the first of a new scan
+    bool isSync() const;
+
+    // Returns the angle in degrees as a float
+    float getAngleDegrees() const;
+
+    // Returns the angle as a raw fixed point value
+    uint16_t getAngleRaw() const;
+
+    // Returns the range measurement
+    uint16_t getDistance() const;
+
+    // Returns the signal strength as an integer value between 0 and 255
+    uint8_t getSignalStrength() const;
+
+    // Returns the signal strength as a float normalized between 0 and 1
+    float getNormalizedSignalStrength() const;
+
+  private:
+    // Scaling factor of raw angle
+    static constexpr float SCALING_FACTOR = 16.0f;
+
+    bool _bIsSync;           // 1 -> first reading of new scan, 0 otherwise
+    uint16_t _rawAngle;      // fixed point value: (degrees * 16)
+    uint16_t _distance;      // cm
+    uint8_t _signalStrength; // 0:255, higher is better
+};
+
+#endif