feat(library): Add full telemetry support

[ZZ-Cat]

Overview

I am finally getting around to adding full telemetry feedback.
Instead of putting each telemetric category into its own Issue-and-Pull-Request combo (which is more time consuming and harder to keep track of), I have decided to put all of the outstanding telemetry categories into this Pull Request to make it easier for myself to track the development progress.

Here is a list of what's being implemented:

• Attitude
• Barometric Altitude and Variometer
• Battery
• Flight Modes
• GPS

Also, I am documenting all telemetry here, so that it's easier for you to refer back to this Pull Request any time you need to.
This is also a reminder to myself to update the documentation, and I am thinking of shutting down my ReadTheDocs link to the project in favour of a better documentation host platform.

Configuration

The file you are looking for is CFA_Config.hpp.
This is where you can tailor CRSF for Arduino to suit your individual needs.

Options

Here is a run-down of the configuration options that this Pull Request brings...

Options	Description	Default value
CRSF_RC_ENABLED	Use this to globally enable or disable receiving and parsing of RC Channels.	1
CRSF_RC_MAX_CHANNELS	This sets the maximum number of RC Channels you can receive.	16
CRSF_RC_CHANNEL_MIN	Sets the minimum channel value.	172
CRSF_RC_CHANNEL_MAX	Sets the maximum channel value.	1811
CRSF_RC_CHANNEL_CENTER	Sets the centre value of all channels.	992
CRSF_RC_INITIALISE_CHANNELS	When enabled, all channels are initialised with CRSF_RC_CHANNEL_CENTER value.	1
CRSF_RC_INITIALISE_THROTTLECHANNEL	When enabled, the Throttle Channel will be initialised with CRSF_RC_CHANNEL_MIN value. Otherwise, it will be initialised with the value determined by CRSF_RC_INITIALISE_CHANNELS option.	1
CRSF_FLIGHTMODES_ENABLED	When enabled, you have access to an event-driven API that allows you to easily implement flight modes in your firmware, and assign each Flight Mode to a switch on your controller.	0
CRSF_TELEMETRY_ENABLED	Use this to globally enable or disable Telemetry output.	1
CRSF_TELEMETRY_ATTITUDE_ENABLED	Enables or disables Attitude Telemetry output.	1
CRSF_TELEMETRY_BAROALTITUDE_ENABLED	Enables of disables Barometric Altitude and Variometer Telemetry output.	1
CRSF_TELEMETRY_BATTERY_ENABLED	Enables or disables Battery Telemetry output.	1
CRSF_TELEMETRY_FLIGHTMODE_ENABLED	Enables or disables Flight Mode Telemetry output.	0
CRSF_TELEMETRY_GPS_ENABLED	Enables or disables GPS Telemetry output.	1
CRSF_DEBUG_ENABLED	Enables debug output over the selected serial port.	0
CRSF_DEBUG_SERIAL_PORT	Use this to select the serial port to be used for debug output.	Serial

Limitations

• CRSF for Arduino will not compile, if CRSF_RC_ENABLED and CRSF_TELEMETRY_ENABLED are both set to 0.
• Setting CRSF_RC_ENABLED to 0 turns off the ability to receive and parse RC channels.
• Likewise for setting CRSF_TELEMETRY_ENABLED to 0 and the ability to send telemetry back to your controller.
• CRSF_RC_INITIALISE_THROTTLECHANNEL will only work if CRSF_RC_ENABLED and CRSF_RC_INITIALISE_CHANNELS are set to 1 - IE Enabled.
• You should not set CRSF_RC_MAX_CHANNELS any higher than what the number of RC channels that the CRSF Protocol provides. This is limited to 16 channels.
• Sketches using CRSF for Arduino's API functions that are governed by CFA_Config.hpp will successfully compile and flash with impunity. But, when their configuration is disabled, these API functions will "silently fail". This is by design.

Flight Modes API

While I was working on adding Flight Modes Telemetry, I took the liberty of giving this category its own bespoke API.
This is disabled by default and you must enable it by setting both CRSF_RC_ENABLED and CRSF_FLIGHTMODES_ENABLED to 1 in CFA_Config.hpp.
This is because the Flight Modes API depends on the RC Channels to determine the actual mode.

Functions

CRSFforArduino::setFlightMode(serialReceiver::flightModeId_t flightMode, uint8_t channel, uint16_t min, uint16_t max)
This function registers your chosen Flight Mode with your selected channel.
The min and max parameters determine the channel range that is considered to be your chosen mode.

CRSFforArduino::setFlightModeCallback(void (*callback)(serialReceiver::flightModeId_t flightMode))
This function registers an event callback where you write your Flight Modes implementation.

Telemetry

Attitude Telemetry

This is your roll, pitch, and yaw values. It is often fed into an artificial horizon indicator on your controller (if you're using a "glass cockpit" Lua script on your controller).
Each value is in decidegrees and are 16-bit unsigned values.

The table below shows how the decidegree input values per axis translate to the Degree SI Unit:

Data Type	Axis	Value	SI Unit
int16_t	Pitch	200	20°
int16_t	Roll	150	15°
int16_t	Yaw	300	30°

To use Attitude Telemetry in your code, use this function:
CRSFforArduino::telemetryWriteAttitude(int16_t roll, int16_t pitch, int16_t yaw)

Barometric Altitude and Variometer Telemetry

There isn't a lot of objective and unbiased knowledge for this telemetric category.
From what I understand of it, you feed data into this from your barometric pressure sensor.
Altitude data is in decimetres and Variometer data is in centimetres per second.

The table below shows how the input values translate to their SI Unit equivalent:

Data Type	Name	Value	SI Unit
uint16_t	Altitude	100	10 metres
int16_t	Variometer	273	2.73 metres per second

To use Barometric Altitude Telemetry in your code, use this function:
CRSFforArduino::telemetryWriteBaroAltitude(uint16_t altitude, int16_t vario)

Battery Telemetry

This is one of the main categories that you use.
Here, you have access to your battery's voltage, current, and energy consumption. Plus, how much percentage of that energy is left in your battery.

The table below shows how each value translate to its SI Unit equivalent:

Data Type	Name	Value	SI Unit
float	Voltage	385.0	3.85 volts
float	Current	150.0	1.5 amperes
uint32_t	Energy Consumption (AKA "Fuel")	100	100 milliampere-hours
uint8_t	Percent Remaining	50	50%

To use Battery Telemetry in your code, use this function:
CRSFforArduino::telemetryWriteBattery(float voltage, float current, uint32_t fuel, uint8_t percent)

Flight Modes

These are text-based and are usually fed into your "glass cockpit" Lua script to give both visual and audible alerts to the state of your drone.

Flight Modes telemetry is crucial for some flight controllers and ground stations to work effectively, as this is used to provide a deterministic way of knowing what state your drone is in at all times.

Here is a list of the current supported Flight Modes:

• Disarmed (written as a * and appended to the end of one of the modes below)
• Acro
• Failsafe
• Wait (which is used to indicate that you should wait for a GPS fix before arming)
• GPS Rescue
• Passthrough
• Angle
• Horizon
• "Air Mode"

These are the same modes used in Betaflight.
The initial support only adds in Betaflight's Flight Modes. I may add in others either as time marches on, or if someone requests it by opening an Issue.

To use the Flight Mode Telemetry in your code, use this function:
CRSFforArduino::telemetryWriteFlightMode(serialReceiver::flightModeId_t flightMode)

GPS

Better known as GNSS, because GPS has been obsolete for quite some time.
This provides you with location and altitude data.

The table below shows how each value translate to its SI Unit equivalent:

Data Type	Name	Value	SI Unit
float	Latitude	-41.182194	-41.182194°
float	Longitude	174.9497	174.9497°
float	Altitude	100.0	1 metre
float	Ground Speed	500.0	18 kilometres per hour
float	Ground Course	275.8	275.8°
uint8_t	Satellites	7	7 Satellites in View

To use GPS Telemetry in your code, use this function:
CRSFforArduino::telemetryWriteGPS(float latitude, float longitude, float altitude, float speed, float groundCourse, uint8_t satellites)

Additional

• Expedite definitions in telemetry.hpp to a separate configuration header and make it easily accessible to the Sketch Layer.

By the time I am finished with this Pull Request, you can use CRSF for Arduino with scripts such as iNav's telemetry widget in your controller.
You're welcome. =^/.~=