Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(link statistics): Add Link Statistics API #78

Merged
merged 5 commits into from
Feb 5, 2024
Merged

Conversation

ZZ-Cat
Copy link
Owner

@ZZ-Cat ZZ-Cat commented Feb 5, 2024

Overview

This Pull Request introduces the ability to read link statistics from the CRSF data stream, using an event-driven API.

Details

  • In CFA_Config.hpp, CRSF_LINK_STATISTICS_ENABLED is set to 1 by default, thus enabling CRSF for Arduino's ability to read link statistics.
  • CRSFforArduino::setLinkStatisticsCallback(serialReceiverLayer::link_statistics_t) is used to set your desired callback function for reading the incoming link statistics.

The following example highlights the new API...

#include "CRSFforArduino.hpp"

/* Declare a null pointer to CRSF for Arduino. */
CRSFforArduino *crsf = nullptr;

/* This needs to be up here, to prevent compiler warnings. */
void onLinkStatisticsUpdate(serialReceiverLayer::link_statistics_t);

void setup()
{
    Serial.begin(115200);
    while (!Serial)
    {
        delay(10);
    }

    Serial.println("Link Statistics Example.");

    /* Initialise CRSF for Arduino. */
    crsf = new CRSFforArduino();

    if (!crsf->begin())
    {
        Serial.println("CRSF for Arduino failed to initialise.");

        delete crsf;
        crsf = nullptr;

        while (1)
        {
            delay(10);
        }
    }

    /* Set your link statistics callback. */
    crsf->setLinkStatisticsCallback(onLinkStatisticsUpdate);

    /* Example firmware is ready. */
    Serial.println("Ready.");
    delay(1000);
}

void loop()
{
    /* Update CRSF for Arduino in the main loop. */
    crsf->update();
}

void onLinkStatisticsUpdate(serialReceiverLayer::link_statistics_t linkStatistics)
{
    /* Here is where you can read out the link statistics.
    You have access to the following data:
    - RSSI (dBm)
    - Link Quality (%)
    - Signal-to-Noise Ratio (dBm)
    - Transmitter Power (mW) */
    static unsigned long lastPrint = 0;
    if (millis() - lastPrint >= 200)
    {
        lastPrint = millis();
        Serial.print("Link Statistics: ");
        Serial.print("RSSI: ");
        Serial.print(linkStatistics.rssi);
        Serial.print(", Link Quality: ");
        Serial.print(linkStatistics.lqi);
        Serial.print(", Signal-to-Noise Ratio: ");
        Serial.print(linkStatistics.snr);
        Serial.print(", Transmitter Power: ");
        Serial.println(linkStatistics.tx_power);
    }
}

Additional notes

The Link Statistics Event only fires when complete CRSF packets are received.
ExpressLRS receivers emit several Link Statistics packets for about five seconds after the receiver has gone into Fail-Safe state.
This is reliable enough to see whether-or-not the receiver has lost connection with the transmitter.
By watching the Link Quality value, we can determine the stability of the connection, plus whether-or-not there's a Fail-Safe.

@ZZ-Cat ZZ-Cat linked an issue Feb 5, 2024 that may be closed by this pull request
@ZZ-Cat ZZ-Cat self-assigned this Feb 5, 2024
@ZZ-Cat ZZ-Cat added ✨️ Enhancement ✨️ New feature or request ...in progress 🚧 Development on this is in progress labels Feb 5, 2024
@ZZ-Cat ZZ-Cat added this to the Version 1.0.0 milestone Feb 5, 2024
@ZZ-Cat ZZ-Cat merged commit 0be68e2 into Main-Trunk Feb 5, 2024
4 checks passed
@ZZ-Cat ZZ-Cat deleted the ZZ-Cat/issue73 branch February 5, 2024 22:52
@ZZ-Cat ZZ-Cat removed the ...in progress 🚧 Development on this is in progress label Feb 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
✨️ Enhancement ✨️ New feature or request
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

Process link statistics from incoming packets.
1 participant