Release 1.0.0

Code updated and tested on one board ready for initial release.

Main changes are to clarify which variables are class and which are
instance and to add looping through multiple boards. Multiple board
testing will happen soon and will be logged on hackaday.

https://hackaday.io/project/19950-hc-sr04-i2c-octopus-octosonar

.gitattributes

@@ -0,0 +1,17 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+
+# Standard to msysgit
+*.doc	 diff=astextplain
+*.DOC	 diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF	 diff=astextplain
+*.rtf	 diff=astextplain
+*.RTF	 diff=astextplain

.gitignore

@@ -0,0 +1,87 @@
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# =========================
+# Operating System Files
+# =========================
+
+# OSX
+# =========================
+
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Windows
+# =========================
+
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Arduino IDE
+.development
+src.ino
+
+# vim
+*~
+*.swp

README.md

@@ -5,20 +5,26 @@ LINKS HERE
 
 ## Summary
 
-This is a library for the Arduino IDE that allows the polling of multiple ultrasonic distance sensors using the I2C bus and a single hardware interrupt pin. It assumes a PCF8574(A) type port expander to trigger the sensors, and tri-state buffers to multiplex the echo signals. It is specifically developed and maintained to support the author's OctoSonar boards version 2.0+. For earlier boards see the SonarI2C library.
+This is a library for the Arduino IDE that allows the polling of multiple ultrasonic distance sensors using the I2C 
+bus and a single hardware interrupt pin. It assumes a PCF8574(A) type port expander to trigger the sensors, and 
+tri-state buffers to multiplex the echo signals. It is specifically developed and maintained to support the author's 
+OctoSonar boards version 2.0+. For earlier boards see the SonarI2C library.
 
-It has been developed for use with the HC-SR04 sensor - and has been tested with units from moultiple manufacturers.
+It has been developed for use with the HC-SR04 sensor - and has been tested with units from multiple manufacturers.
 
 ## Supported Platforms
 
-This library is designed to work with the Arduino IDE versions 1.6.x or later; it is not tested it with earlier versions. It should work with any Arduino compatible board with an available hardware interrupt pin. Note that other interrupt activity may interfere with the accuracy and reliability of this code.
+This library is designed to work with the Arduino IDE versions 1.6.x or later; it is not tested it with earlier versions. It should work with any Arduino compatible board with an available hardware interrupt pin. Note that other interrupt 
+activity may interfere with the accuracy and reliability of this code.
 
 ## Getting Started
 
 ### Hardware
 
 This code supports the OctoSonar v2.0 and later. Schematics and board designs are included in this repo.
 
+Boards and sensors can be purchased at [on Tindie.](https://www.tindie.com/stores/arielnh56/)
+
 The board should be connected to your controller as follows:
 
 * GND -> GND
@@ -28,13 +34,22 @@ The board should be connected to your controller as follows:
 * INT -> a hardware interrupt pin (2 or 3 on the UNO)
 * 5V -> a 5V supply (VCC on the UNO)
 
-Note that the 5V supply drives the sensors and the VCC drives the electronics. This should allow the unit to be supported by 3.3V controllers (some other Arduino formats and Raspberry Pi). This 3.3V mode is not yet tested and validated - USE AT YOUR OWN RISK. If you want to save a wire with a 5V controller there is a solder jumper on the back of the board to connect the 5V and VCC pins together.
+Note that the 5V supply drives the sensors and the VCC drives the electronics. This allows the unit to be supported
+on 3.3V controllers (some Arduino formats and Raspberry Pi, Teensy etc). You can save a wire on a 5V controller
+by connecting the 5V and VCC pins together via the V1 solder jumper.
 
 As manufactured the board has an I2C address of 0x38. This can be altered via solder jumpers on the back.
 
+The I2C bus **requires** pullup resistors on the SDA and SCL lines to VCC. While Arduinos will enable the
+internal pullups, these are too large at 20k\omega - 50k\omega for reliable operation of I2C. The generally recommended 
+value to use is 4.7k\omega. Positions are provided on the board at R1 and R2 to add these pullup resistors. On my 
+projects I usually have several devices on the bus and place the pullups near the controller. For more information on
+use of the I2C bus there is an [excellent Sparkfun tutorial.](https://learn.sparkfun.com/tutorials/i2c)
+
 ### Software
 
-If you are using version 1.6.2 or later of the [Arduino software (IDE)](http://www.arduino.cc/en/Main/Software), you can use the Library Manager to install this library:
+If you are using version 1.6.2 or later of the [Arduino software (IDE)](http://www.arduino.cc/en/Main/Software), you 
+can use the Library Manager to install this library:
 
 1. In the Arduino IDE, open the "Sketch" menu, select "Include Library", then "Manage Libraries...".
 2. Search for "OctoSonar".
@@ -52,63 +67,84 @@ If this does not work, you can manually install the library:
 
 ## Examples
 
-An example is included showing the use of the OctoSonar with 8 sensors. It will display the 8 measurement on an LCDand the serial monitor. It supports 1602 and 2004 LCDs.
+An example is included showing the use of the OctoSonar with 8 sensors. It will display the 8 measurement on LCD and the serial monitor. It supports 1602 and 2004 LCDs.
+
 ## Library reference
 
 * Constructor. Call once outside loop() and setup(). This sets the I2C address of the pin expander (0x38 - 0x3F).
+e.g.  OctoSonar() myOcto;
 
  ```c
-    OctoSonar(uint8_t address); // constructor
+    OctoSonar(); // defaults constructor 0x38, 2
+    OctoSonar(uint8_t address, uint8_t interrupt); // constructor
+
 ```
 
-* call one of the begin() functions from setup(). This sets the interrupt pin to use.
+* call one of the begin() functions from setup(). The second one of these lets you set the active ports up front.
+e.g. myOcto.begin();
 
  ```c
-    static void begin();                                     // call from setup(). Defaults to pin 2 and 50ms
-    static void begin(uint8_t interrupt);                    // same thing but set the pin
+    void begin();
+    void begin(uint8_t active);
 ```
 
-* by default we skip one out of range/failed echo,keeping the last value. It may be useful to raise this count in sub-optimal echo environments.
+*  Disabling sensors that you are not interested in right now allows the other sensors to poll more often. This is a bitmask mapping to the 8 sensors on the unit. A '1' is 'active'. 
+e.g. myOcto.active = 0x03;   // S0 and S1 only
 
  ```c
-    static uint8_t maxOOR;                                   // how many OOR to skip. Raise this in noisy environments
+    uint8_t active;                    // mask of active sensors 
 ```
 
-* by default the output is in mm. You can change this by setting this to OCTOSONAR_CM for cm, or OCTOSONAR_IN for inches. It is the value needed to conver from microseconds to the desired unit.
+* by default we skip one out of range/failed echo, keeping the last value. It may be useful to raise this count in sub-optimal echo environments. This is a global setting.
+e.g. OctoSonar::maxOOR = 2;
 
  ```c
-    static double units;                        // defaults to OCTOSONAR_MM 
+    static uint8_t maxOOR;                                   // how many OOR to skip. Raise this in noisy environments
 ```
 
-*  Disabling sensors that you are not interested in right now allows the other sensors to poll more often. This is a bitmask mapping to the 8 sensors on the unit. A '1' is 'active'.
+* by default the output is in mm. You can change this by setting this to OCTOSONAR_CM for cm, or OCTOSONAR_IN for inches. It is the value needed to convert from microseconds to the desired unit. This is a global setting.
+e.g. OctoSonar::units = OCTOSONAR_IN;
 
  ```c
-    static uint16_t active;                    // mask of active sensors 
+    static double units;                        // defaults to OCTOSONAR_MM 
 ```
 
-* Call this every loop(). If it is time, it will poll the next enabled sensor.
+* Call this every loop(). If it is time, it will poll the next enabled sensor. 
+e.g. OctoSonar::doSonar();
 
  ```c
     static void doSonar();
 ```
 
-* Return values. By default, when the sensor does not get a good echo a zero value is returned. Using the second form of read() allows you to set you own preference for what is returned. The returned value defaults to mm.
+* Return values. By default, when the sensor does not get a good echo a zero value is returned. Using the second
+  form of read() allows you to set your own preference for what is returned. The returned value defaults to mm.
+e.g. int16_t distance = myOcto.read(1);  // read distance from S1
  ```c
     int16_t read(uint8_t sonar);                     
     int16_t read(uint8_t sonar, int16_t outOfRange);
 ```
+
+## Using multiple boards
+The code is written to support multiple OctoSonar units on the same or different interrupt pins. It will cycle
+through all the active sensors on one board, then move on to the next board, in a loop. It will not poll 
+multiple boards in
+parallel. At the time of writing (6/30/2017) I haven't actually tested this multi-board capability. It uses 
+similar logic to that used in the earlier SonarI2C library, except the it is the boards that are in a 
+looped-linked-list not the sensors.
  
 ## Relationship to SonarI2C
 
-This is a rework of the SonarI2C concept, and borrows a lot from it. It is structurally different so I'm starting a new repo.
+This is a rework of the SonarI2C concept, and borrows a lot from it. It is structurally different so I'm
+ starting a new repo.
 
 The main differences are:
 * the use of tri-state buffers to mux the echo signals
 * the trigger pulse is held down for the duration of each sensor. The falling edge triggers the HC-SR04, and the low value is used to enable the 
 matching tri-state buffer to forward the echo signal
-* the unit of thing is now the board, not the sensor. No daisy-chaining. That was silly.
+* the unit of thing is now the board, not the sensor. 
+* No daisy-chaining. That was silly.
 
 ## Version history
 
-* 0.0.0 (DATE HERE): not released.
+* 1.0.0 (06/30/2017): Initial release
 

library.properties

@@ -1,9 +1,9 @@
 name=OctoSonar
-version=0.0.1
+version=1.0.0
 author=Alastair Young <alastair@redhunter.com>
 maintainer=Alastair Young <alastair@redhunter.com>
-sentence=A library to support cheap ultrasonic sensors on I2C bus
-paragraph=triggers via PCF8574, echo via tri state buffer.
+sentence=A library to support the OctoSonar v2 HC-SR04 concentrator
+paragraph=triggers via PCF8574A, echo via tri state buffer.
 category=Sensors
 url=http://redhunter.com/
 architectures=*