Changed ScanPacket from struct to class

johnsonb2 · johnsonb2 · commit 9bd2010fad9a · 2017-09-06T12:10:52.000-07:00
Expanded the ScanPacket struct into a class with a constructor, getter, and
 setter methods
Changed ScanPacket to store angle as raw 16-bit fixed point value instead of
 float
Added getter methods to ScanPacket class to get angle as degrees,
 millidegrees, or raw fixed point value
Added constants defining bit flags for each of the error/sync bits in data
 blocks
Moved the Sweep data member bIsScanning from public to private access and
 added a getter method for this value
Removed const type qualifier on return type of _ascii_bytes_to_integer
Updated README
Updated keywords
Minor formatting changes
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@ 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 |
 | :------------: | :-----------: |
@@ -19,7 +19,7 @@ Copy the entire `Sweep/` folder to your `.../Arduino/libraries/` directory.
 
 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,46 @@ 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++
+float getAngleMillidegrees() const
+```
+
+Returns the angle of this reading as a float, in millidegrees.
+
+```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. A low value indicates low strength, and a high value indicates high strength.
diff --git a/Sweep/Examples/MegaDistanceBlink/MegaDistanceBlink.ino b/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();
-}
+}
diff --git a/Sweep/Examples/MegaSerialPrinter/MegaSerialPrinter.ino b/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;
-}
+}
diff --git a/Sweep/ScanPacket.cpp b/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;
+}
+
+float ScanPacket::getAngleMillidegrees() const
+{
+    return (_rawAngle / SCALING_FACTOR) * MILLIDEGREE_FACTOR;
+}
+
+uint16_t ScanPacket::getAngleRaw() const
+{
+    return _rawAngle;
+}
+
+uint16_t ScanPacket::getDistance() const
+{
+    return _distance;
+}
+
+uint8_t ScanPacket::getSignalStrength() const
+{
+    return _signalStrength;
+}
diff --git a/Sweep/ScanPacket.h b/Sweep/ScanPacket.h
@@ -0,0 +1,46 @@
+#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 in millidegrees as a float
+    float getAngleMillidegrees() 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
+    uint8_t getSignalStrength() const;
+
+  private:
+    // Scaling factor of raw angle
+    static constexpr float SCALING_FACTOR = 16.0;
+    // Millidegrees conversion factor
+    static constexpr float MILLIDEGREE_FACTOR = 1000;
+
+    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
diff --git a/Sweep/Sweep.cpp b/Sweep/Sweep.cpp
@@ -1,14 +1,17 @@
 #include "Sweep.h"
 
-Sweep::Sweep(Stream &serial) : _serial(serial)
-{
-    bIsScanning = false;
-}
+Sweep::Sweep(Stream &serial) : _serial(serial), bIsScanning(false) {}
+
 Sweep::~Sweep()
 {
     _serial.flush();
 }
 
+bool Sweep::isScanning()
+{
+    return bIsScanning;
+}
+
 bool Sweep::startScanning()
 {
     if (bIsScanning)
@@ -50,23 +53,37 @@ bool Sweep::stopScanning()
     return false;
 }
 
-bool Sweep::getReading(ScanPacket &reading)
+ScanPacket Sweep::getReading(bool &success)
 {
+    success = false;
     if (!bIsScanning)
-        return false;
+    {
+        return ScanPacket(false, 0, 0, 0);
+    }
 
-    // wait for the receipt (possible timeout)
+	// wait for the receipt (possible timeout)
     if (_readResponseScanPacket())
     {
         // TODO: validate receipt
-        reading.bIsSync = _responseScanPacket[0] % 2 == 1;
-        // convert the angle into a float in degrees
-        reading.angle = angle_raw_to_deg((_responseScanPacket[2] << 8) + (_responseScanPacket[1]));
-        reading.distance = (_responseScanPacket[4] << 8) + (_responseScanPacket[3]);
-        reading.signalStrength = _responseScanPacket[5];
-        return true;
+        int i = 0;
+
+        bool bIsSync = _responseScanPacket[i++] & _SYNC_MASK;
+
+        uint16_t angle_lsb = _responseScanPacket[i++];
+        uint16_t angle_msb = _responseScanPacket[i++] << 8;
+        uint16_t angle = angle_lsb + angle_msb;
+
+        uint16_t distance_lsb = _responseScanPacket[i++];
+        uint16_t distance_msb = _responseScanPacket[i++] << 8;
+        uint16_t distance = distance_lsb + distance_msb;
+
+        uint8_t signalStrength = _responseScanPacket[i++];
+
+        success = true;
+        return ScanPacket(bIsSync, angle, distance, signalStrength);
     }
-    return false;
+	
+    return ScanPacket(false, 0, 0, 0);
 }
 
 bool Sweep::getMotorReady()
diff --git a/Sweep/Sweep.h b/Sweep/Sweep.h
diff --git a/Sweep/keywords.txt b/Sweep/keywords.txt
