Document the RFM95 and GPS classes.

docs/rfm95.rst

@@ -1,2 +1,47 @@
 RFM95 support
 -------------
+
+* Header: ``feather/wing/rfm95.h``
+* Link (Featherwing): `RFM95W 900 MHz Radiofruit <https://www.adafruit.com/product/3231>`__
+* Link (Feather M0 with RFM95): `Adafruit Feather M0 with RFM95 LoRa Radio - 900MHz <https://www.adafruit.com/product/3178>`__
+* Update task: nothing is done
+
+The ``RFM95`` class is used both for the Featherwing and the onboard
+radio. There are a few defines that can be overridden, which should
+be done in the ``platformio.ini`` config. These default to valid values
+for the Feather M0 with RFM95 for use in the US.
+
+* ``LORA_FREQ`` defaults to ``915.0``, which is valid in the US.
+* ``RFM95_CS`` defaults to ``8``.
+* ``RFM95_RST`` defaults to ``4``.
+* ``RFM95_INT`` (which is the radio interrupt or IRQ pin) defaults to ``3``.
+
+The wiring instructions for the Featherwing are on 
+`Adafruit's site <https://learn.adafruit.com/radio-featherwing/wiring>`__.
+
+There are two constructors:
+
+* ``RFM95()`` uses the values from the three ``RFM95_`` defines above.
+* ``RFM95(uint8_t cs, uint8_t irq, uint8_t rst)`` allows setting the
+  pins explicitly.
+
+The ``setup`` method will initialise the radio, set it to the appropriate
+frequency, and set it to maximum transmit power. The transmit power can be
+set using the ``setPower`` method, described below.
+
+The class provides the following methods:
+
+* ``bool available()`` returns true if the radio has received data.
+* ``void setPower(uint8_t)`` changes the transmit power. Valid values
+  are in the range 5 to 23, inclusive, with higher values providing
+  more transmit power. As per the docs, this uses the ``PA_BOOST`` pin
+  to provide higher transmit power.
+* ``void transmit(uint8_t *buf, uint8_t len, bool blocking)`` sends
+  the message contained in ``buf``; if ``blocking`` is true, the method
+  will block until transmission is complete.
+* ``bool receive(uint8_t *buf, uint8_t *len, int16_t *rssi)`` returns true
+  if a message is available. ``buf`` must have at least 251 bytes available,
+  which is the maximum message length for an RFM95 message. If ``rssi`` is
+  not NULL, it will be set to the received signal strength. The message length
+  will be returned via ``len``.
+

docs/ultimate_gps.rst

@@ -1,2 +1,55 @@
 Ultimate GPS Featherwing
 ------------------------
+
+* Header: ``feather/wing/gps.h``
+* Link: `Adafruit Ultimate GPS FeatherWing <https://www.adafruit.com/product/3133>`
+* Update task: checking the GPS for new data and updating the fix and position data
+
+The GPS Featherwing is a standard serial-based GPS. It is instantiated using one of
+two constructors:
+
+* ``GPS()`` will use ``Serial1`` for communicating with the GPS.
+* ``GPS(HardwareSerial *)`` will use the given hardware serial port.
+
+GPS position data is returned using the following structures::
+
+  typedef struct {
+          uint16_t        year;
+          uint8_t         month;
+          uint8_t         day;
+          uint8_t         hour;
+          uint8_t         minute;
+          uint8_t         second;
+  } Time;
+  
+  typedef struct {
+          uint8_t quality;
+          uint8_t satellites;
+  } Fix;
+  
+  typedef struct {
+          float   latitude;
+          float   longitude;
+          Time    timestamp;
+          Fix     fix;
+  } Position;
+
+The ``setup`` method will set up the serial connection to the GPS and tell
+it to return the standard position data (aka ``RMCGGA``) and to send updates
+every second. This can be overriden using the ``GPS_MODE`` and ``GPS_UPDATE_FREQ``
+defines, which should be set in ``platformio.ini``. It also expects the GPS to
+be communicating at a baudrate of 9600; this can be overridden with the 
+``GPS_BAUDRATE`` define.
+
+The ``GPS`` class provides the following methods for working with
+position data:
+
+* ``bool haveFix()`` returns true if the GPS has a fix.
+* ``bool position(Position &pos)`` returns true if the GPS has a valid fix and
+  fills in the ``Position`` struct with the most recent fix data.
+* ``void dump()`` will block and echo data from the GPS serial port to the
+  serial console. This might be useful for debugging GPS issues.
+
+The ``GPS`` class is also an instance of the ``Clock`` virtual class,
+and therefore provides the relevant RTC methods.
+

include/feather/wing/gps.h

@@ -8,6 +8,19 @@
 #include <feather/wing/wing.h>
 
 
+#ifndef GPS_MODE
+#define GPS_MODE	PMTK_SET_NMEA_OUTPUT_RMCGGA
+#endif // GPS_MODE
+
+#ifndef GPS_UPDATE_FREQ
+#define GPS_UPDATE_FREQ	PMTK_SET_NMEA_UPDATE_1HZ
+#endif // GPS_UPDATE_FREQ
+
+#ifndef GPS_BAUDRATE
+#define GPS_BAUDRATE	9600
+#endif // GPS_BAUDRATE
+
+
 // Time is a basic timestamp to simplify serialisation.
 typedef struct {
 	uint16_t	year;

src/wing_gps.cc

@@ -8,10 +8,12 @@
 bool	
 GPS::setup()
 {
-	gps.begin(9600);
-	gps.sendCommand(PMTK_SET_NMEA_OUTPUT_RMCGGA);
-	gps.sendCommand(PMTK_SET_NMEA_UPDATE_1HZ); // 1 Hz update rate
+	gps.begin(GPS_BAUDRATE);
+	gps.sendCommand(GPS_MODE);
+	gps.sendCommand(GPS_UPDATE_FREQ);
+#ifndef GPS_NO_ANTENNA_UPDATES
 	gps.sendCommand(PGCMD_ANTENNA);
+#endif // GPS_NO_ANTENNA_UPDATES
 	delay(500);
 	return true;
 }