Merge pull request #45 from mathertel/feature_Si4721

Feature Si4721 for receiving and transmitting.
Much help from NPoole and sparkfun for supporting a board .

See [README.md](README.md) and [CHANGELOG.MD](CHANGELOG.MD)

.gitignore

@@ -18,4 +18,9 @@
 # Executables
 *.exe
 *.out
-*.app
+*.app
+
+/temp
+/.vscode
+/.development
+_*

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2020-09-17 
+
+> **Important changes**
+>
+> This release focuses adding the si4721 radio chip to the library. The adoption was done using the board from sparkfun you can find here:
+> <https://www.sparkfun.com/products/15853>.
+> 
+> This chip also supports sending FM signals, there is a special example 'TransmitSI4721.ino' to show this functionality.
+
+Thanks to [@NPoole](https://github.com/NPoole) for adding the adoption of the si4721 chip.
+
+
+### Added Examples
+
+* **[TestSI4721.ino](/examples/TestSI4721/TestSI4721.md)** - This is the simple fixed settings example to proof correct functionality and wiring.
+
+* **[TransmitSI4721.ino](/examples/TransmitSI4721/TransmitSI4721.md)** - This example shows how to implement FM transmission using the SI4721 chip. Please respect your local radio transmission policies and rules by your govermant.
+
+
+
+### Enhancements
+
+* The base radio class implementations now has some I2c utility routings that will be further adopted in the chip libraries.
+* Some code to initialize the I2C bus has beed added to the examples to support ESP8266 boards.
+
+### Fixes
+
+With some chips that support multiple modes the power up should be handles when specifying the mode in setBand and power situation will be handled according the following schema:
+
+* The init() function establishes communication with the radio chip. As a result the radio chip will not yet work and is in power down state.
+* The setBand() function will configure the radio chip and start operation. The radio chip will be in power up state.
+* The term() function will stop any operation. The radio chip will be in power down state. Communication with the chip will still work.
+* To implement a "standby" functionality setBand() for "on" and term() for "standby" should be used.
+
+This is verified for SI4721 for now.
+
+
+### Known Issues
+
+The TransmitSI4721.ino example and the library doesn't offer all options for transmitting but some basic functionality.
+Improvements are welcome.
+
+---
+
+## Notes
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as used for the Arduino libraries.
+

LICENSE

@@ -1,15 +1,30 @@
-See http://www.mathertel.de/License.aspx
+BSD 3-Clause License
 
-Software License Agreement (BSD License)
-
-Copyright (c) 2005-2014 by Matthias Hertel,  http://www.mathertel.de/
+Copyright (c) 2005-2020, Matthias Hertel,  http://www.mathertel.de/
 
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-�Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 
-�Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 
-�Neither the name of the copyright owners nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. 
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -2,37 +2,63 @@
 
 This library is about controlling an FM radio chips by using an Arduino board and some optional components like a LCD display, a rotary encoder, a LCD+Keyboard shield or an Ethernet Shield to build a standalone radio.
 
-In the [mathertel / Radio](https://github.com/mathertel/Radio) repository on github.com you find an Arduino library for implementing an FM receiver using one of the supported radio chips for receiving FM broadcast audio signals.
+In the [mathertel/Radio](https://github.com/mathertel/Radio) repository on github.com you find an Arduino library for implementing an FM receiver using one of the supported radio chips for receiving FM broadcast audio signals.
 
 There are various examples included that show using the library using different hardware setups.
 
+The library is working for many boards like Arduino, Arduino Mega, ESP8266 and maybe more.
+
+See also the [Changelog](CHANGELOG.md).
+
 ## Documentation
 
-The documentation for the libraries in DOXYGEN style can be found at [http://mathertel.github.io/Radio/html](html/index.html).
+The API documentation for the libraries in DOXYGEN style can be found at [http://mathertel.github.io/Radio/html](html/index.html).
 
-A more detailed article is availabe at [www.mathertel.de/Arduino/RadioLibrary.aspx](http://www.mathertel.de/Arduino/RadioLibrary.aspx).
+A more detailed article is available at [www.mathertel.de/Arduino/RadioLibrary.aspx](http://www.mathertel.de/Arduino/RadioLibrary.aspx).
 
-Currently the following chips are supported:
+Currently the following radio receiver chips are supported:
 
-*   The RDA5807M from RDA Microelectronics
-*   The SI4703 from Silicon Labs
-*   The SI4705 from Silicon Labs
-*   The TEA5767 from NXP
+* The **RDA5807M** from RDA Microelectronics
+* The **SI4703** from Silicon Labs
+* The **SI4705** from Silicon Labs
+* The **SI4721** from Silicon Labs
+* The **TEA5767** from NXP
 
 They all are capable for receiving FM radio stations in stereo with European and US settings and can be controlled by using the I2C bus. However there are differences in the sensitivity and quality and well on receiving RDS information from the stations.
 
 For each of these chips a specific library is implemented that knows how to communicate with the chip using the I2C bus and the wire library. These libraries all share a common base, the radio library so that all the common code is only implemented once in there:
 
 All the libraries share the same interface (defined by the radio library) so it is possible to exchange them when not using one of the chip specific functions.
 
+Currently the following radio transmitter chips are supported:
+
+* The **SI4721** from Silicon Labs
+
+
+## Contributions
+
+Contributions to the library like features, fixes and support of other chips and boards are welcome using Pull Requests.
+
+Please don't ask general programming questions in this project. Radio chip specific questions may be answered by the community (or not) and are closed after some months of inactivity.
+
 ## Examples
 
-Within the Arduino library you can find examples that implement different scenarios to control the radio chips:
+Within the Arduino library you can find examples that implement different scenarios to control various radio chips.
+
+The basic examples only startup the chips and set a static station and volume:LCDKeypadRadio
+* **TestRDA5807M** to test the RDA5807M chip. 
+* **TestSI4703** to test the SI4703 chip.
+* **TestSI4705** to test the SI4705 chip.
+* **TestSI4721** to test the SI4721 chip.
+* **TestTEA5767** to test the TEA5767 chip.
+
+The examples can be used with several chips:
 
-*   The basic examples only startup the chips and set a static station and volume.
-*   The SerialRadio example needs only an arduino and uses the Serial in- and output to change the settings and report information.
-*   The LCDRadio example is similar to SerialRadio but also populates some information to an attached LCD.
-*   The LCDKeypadRadio example uses the popular LCDKeypad shield.
-*   The WebRadio example is the most advanced radio that runs on an Arduino Mega with an Ethernet Shield and an rotator encoder. You can also control the radio by using a web site that is available on the Arduino.
+* The **SerialRadio** example needs only an arduino and uses the Serial in- and output to change the settings and report information.
+* The **ScanRadio** is similar to the SerialRadio example but includes some experimental scanning approaches.
+* The **LCDRadio** example is similar to SerialRadio but also populates some information to an attached LCD.
+* The **LCDKeypadRadio** example uses the popular LCDKeypad shield.
+* The **WebRadio** example is the most advanced radio that runs on an Arduino Mega with an Ethernet Shield and an rotator encoder. You can also control the radio by using a web site that is available on the Arduino.
 
+The only sending example for the SI4721 chip can be found in **TransmitSI4721**.
 

examples/LCDKeypadRadio/LCDKeypadRadio.ino

@@ -42,6 +42,7 @@
 #include <rda5807M.h>
 #include <si4703.h>
 #include <si4705.h>
+#include <si4721.h>
 #include <tea5767.h>
 
 #include <RDSParser.h>
@@ -90,7 +91,8 @@ int    i_sidx=5;        ///< Start at Station with index=5
 // RADIO radio;       ///< Create an instance of a non functional radio.
 // RDA5807M radio;    ///< Create an instance of a RDA5807 chip radio
 // SI4703   radio;    ///< Create an instance of a SI4703 chip radio.
-SI4705   radio;    ///< Create an instance of a SI4705 chip radio.
+// SI4705   radio;    ///< Create an instance of a SI4705 chip radio.
+SI4721   radio;    ///< Create an instance of a SI4721 chip radio.
 // TEA5767  radio;    ///< Create an instance of a TEA5767 chip radio.
 
 
@@ -234,7 +236,7 @@ void setup() {
 
   radio.setMono(false);
   radio.setMute(false);
-  // radio.debugRegisters();
+  // radio._wireDebug();
   radio.setVolume(8);
 
   Serial.write('>');
@@ -307,4 +309,3 @@ void loop() {
 } // loop
 
 // End.
-