You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
299 lines
16 KiB
299 lines
16 KiB
/////////////////////////////////////////////////////////////////////////////////// |
|
// Copyright (C) 2026 Jon Beniston, M7RCE <jon@beniston.com> // |
|
// Some code by AI // |
|
// // |
|
// This program is free software; you can redistribute it and/or modify // |
|
// it under the terms of the GNU General Public License as published by // |
|
// the Free Software Foundation as version 3 of the License, or // |
|
// (at your option) any later version. // |
|
// // |
|
// This program is distributed in the hope that it will be useful, // |
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of // |
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // |
|
// GNU General Public License V3 for more details. // |
|
// // |
|
// You should have received a copy of the GNU General Public License // |
|
// along with this program. If not, see <http://www.gnu.org/licenses/>. // |
|
/////////////////////////////////////////////////////////////////////////////////// |
|
|
|
#ifndef INCLUDE_FEATURE_MCPTOOLS_H_ |
|
#define INCLUDE_FEATURE_MCPTOOLS_H_ |
|
|
|
#include <functional> |
|
|
|
#include <QJsonArray> |
|
#include <QJsonObject> |
|
#include <QJsonValue> |
|
#include <QList> |
|
#include <QMap> |
|
#include <QString> |
|
#include <QMutex> |
|
#include <QSet> |
|
#include <QStringList> |
|
|
|
#include <QAtomicInt> |
|
#include <QObject> |
|
|
|
#include "mcperror.h" |
|
#include "mcpdocs.h" |
|
#include "mcpdatafeed.h" |
|
#include "mcpcapture.h" |
|
|
|
//!< A settings definition's properties, read from the swagger YAML that describe_settings serves. |
|
//!< The current value of a setting cannot serve this purpose: generated SWG objects omit empty |
|
//!< strings, so a blank setting is indistinguishable from a key that does not exist |
|
struct SettingsSchema |
|
{ |
|
bool m_known = false; //!< False when the definition was not found, so nothing can be judged |
|
QMap<QString, QString> m_types; //!< Property name -> YAML type: integer, number, string, array or object |
|
}; |
|
|
|
class WebAPIAdapterInterface; |
|
class MCPStreams; |
|
class DeviceAPI; |
|
class ChannelAPI; |
|
class Feature; |
|
|
|
namespace SWGSDRangel { |
|
class SWGObject; |
|
class SWGErrorResponse; |
|
} |
|
|
|
// Counts MainCore structural change signals so that tool handlers running on HTTP threads |
|
// can wait for asynchronous operations (which complete on the main thread) to finish. |
|
// Lives in the main thread; the counters are read from other threads. |
|
class MCPEventCounter : public QObject |
|
{ |
|
Q_OBJECT |
|
public: |
|
MCPEventCounter(); |
|
|
|
QAtomicInt m_deviceSetAdded; |
|
QAtomicInt m_deviceSetRemoved; |
|
QAtomicInt m_deviceChanged; |
|
QAtomicInt m_channelAdded; |
|
QAtomicInt m_channelRemoved; |
|
QAtomicInt m_featureAdded; |
|
QAtomicInt m_featureRemoved; |
|
|
|
private slots: |
|
void onDeviceSetAdded(int index, DeviceAPI *device); |
|
void onDeviceSetRemoved(int index); |
|
void onDeviceChanged(int index); |
|
void onChannelAdded(int deviceSetIndex, ChannelAPI *channel); |
|
void onChannelRemoved(int deviceSetIndex, ChannelAPI *channel); |
|
void onFeatureAdded(int featureSetIndex, Feature *feature); |
|
void onFeatureRemoved(int featureSetIndex, Feature *feature); |
|
}; |
|
|
|
// The set of MCP tools that control SDRangel. Everything goes through the |
|
// in-process Web API adapter, so what the tools can do matches the REST API, |
|
// plus waiting for asynchronous operations to complete. |
|
class MCPTools |
|
{ |
|
public: |
|
struct Tool |
|
{ |
|
QString name; |
|
QString description; |
|
QJsonObject inputSchema; |
|
std::function<QJsonValue(const QJsonObject& args)> handler; |
|
}; |
|
|
|
explicit MCPTools(WebAPIAdapterInterface *webAPIAdapterInterface); |
|
|
|
QJsonArray listTools() const; |
|
QJsonObject callTool(const QString& name, const QJsonObject& arguments); |
|
|
|
// Data also served as resources |
|
QJsonObject getInstanceSummary(); |
|
QJsonObject getAvailableDevices(int direction = -1); //!< -1 for all directions |
|
QJsonObject getAvailableChannels(int direction = -1); |
|
QJsonObject getAvailableFeatures(); |
|
QJsonObject getPresets(); |
|
QJsonObject getConfigurations(); |
|
QJsonObject getDeviceSet(int deviceSetIndex); |
|
int deviceSetCount() const; |
|
QString describeType(const QString& type, const QString& kind); |
|
MCPDocs& docs() { return m_docs; } |
|
MCPDataFeed& dataFeed() { return m_dataFeed; } |
|
MCPCapture& capture() { return m_capture; } |
|
void setStreams(MCPStreams *streams) { m_streams = streams; } |
|
//!< The feature that owns this server, so it can refuse to delete or stop itself |
|
void setOwnerFeature(const QObject *feature) { m_ownerFeature = feature; } |
|
//!< Set by the server, on the main thread, before it waits for the HTTP threads to finish. |
|
//!< Every wait and sleep in the tools then ends at once with a tool error, since the main |
|
//!< thread they would otherwise be waiting on is the one waiting for them |
|
void setStopping(bool stopping); |
|
|
|
private: |
|
WebAPIAdapterInterface *m_adapter; |
|
MCPEventCounter m_events; |
|
MCPDocs m_docs; |
|
MCPDataFeed m_dataFeed; |
|
MCPCapture m_capture; |
|
MCPStreams *m_streams; |
|
|
|
// Creating an object and working out which one is new must not overlap with another |
|
// creation, or two callers snapshot the same state and both claim the same object. |
|
// The capture tools run without the dispatch lock, so this is reachable. |
|
QMutex m_creationMutex; |
|
// Deletion is by index, and the index is resolved just before the delete is posted for |
|
// the main thread to do later. Two calls deleting on one device set unserialised can post |
|
// two indices that were right when read and wrong once the first delete has renumbered |
|
// the rest, taking a channel neither meant. Held from the lookup to the object being gone |
|
QMutex m_deletionMutex; |
|
// The channels listen and scan have added, so that the next of either on the same device |
|
// set can take them away again and cleanup can remove them all. Held by uid rather than |
|
// pointer: a channel removed from the GUI frees its address for the next one created, |
|
// which must not then be taken for one of these. They run without the dispatch lock, so |
|
// this has a lock of its own, which is never held across addChannelAndWait or a delete: |
|
// those take m_creationMutex or wait |
|
QMutex m_intentMutex; |
|
QSet<uint64_t> m_intentChannels; |
|
// The features listen added for a mode's output (AIS, Radiosonde, APRS), removed again once no |
|
// channel it added still feeds them. A feature that was already there is never among these |
|
QSet<uint64_t> m_intentFeatures; |
|
const QObject *m_ownerFeature; |
|
QAtomicInt m_stopping; |
|
QList<Tool> m_tools; |
|
// The definitions are loaded on first use and the parsed schemas cached as they are asked |
|
// for, from whichever thread asks. The settings tools run under the dispatch lock but |
|
// listen and scan do not, and they patch settings too, so these have a lock of their own, |
|
// taken by describeType and settingsSchema; the helpers they call expect it held |
|
QMutex m_schemaMutex; |
|
QMap<QString, QString> m_yamlDefinitions; //!< Swagger definition name -> YAML text |
|
QMap<QString, QString> m_yamlDefinitionsByLower; //!< Lower cased name -> the name as written |
|
QMap<QString, SettingsSchema> m_schemaCache; //!< Parsed form of the above, by definition name |
|
bool m_yamlLoaded; |
|
|
|
void add(const QString& name, const QString& description, const QJsonObject& inputSchema, |
|
std::function<QJsonValue(const QJsonObject& args)> handler); |
|
|
|
void registerInstanceTools(); |
|
void registerDeviceSetTools(); |
|
void registerChannelTools(); |
|
void registerFeatureTools(); |
|
void registerPresetTools(); |
|
void registerWorkspaceTools(); |
|
void registerCaptureTools(); |
|
void registerIntentTools(); |
|
|
|
//!< Polls until the condition holds, at most timeoutMs. False on timeout; throws when the |
|
//!< server is stopping, as nothing waited for on the main thread will happen then |
|
bool waitFor(const std::function<bool()>& condition, int timeoutMs = m_waitTimeoutMs) const; |
|
//!< A sleep that a stop cuts short, with the same tool error |
|
void pause(int ms) const; |
|
static const int m_waitTimeoutMs = 5000; |
|
|
|
// Device set helpers |
|
int channelCount(int deviceSetIndex) const; |
|
int featureCount() const; |
|
int deviceSetDirection(int deviceSetIndex); |
|
QJsonObject selectDevice(int deviceSetIndex, const QJsonObject& args); |
|
QJsonObject getDeviceSettings(int deviceSetIndex); |
|
QJsonObject patchDeviceSettings(int deviceSetIndex, const QJsonObject& partial); |
|
int addChannelAndWait(int deviceSetIndex, const QString& channelType); |
|
int addFeatureAndWait(const QString& featureType); |
|
int addDeviceSetAndWait(int direction); |
|
//!< Identity of the current channels, features or device sets, to spot which one is new. |
|
//!< Channels and features are identified by UID throughout: a pointer to one is only ever |
|
//!< good until the next wait, since a deleted object's address is reused by the next one |
|
//!< created, and every tool here waits |
|
QSet<uint64_t> channelUids(int deviceSetIndex) const; |
|
QSet<uint64_t> featureUids() const; |
|
QSet<const void *> deviceSetPointers() const; |
|
void deleteChannelAndWait(int deviceSetIndex, int channelIndex); |
|
void deleteChannelLocked(int deviceSetIndex, int channelIndex); //!< With m_deletionMutex held |
|
//!< Removes a device set that listen or scan created and could not finish setting up, if it |
|
//!< is still the last one, which is the only one the API can remove |
|
void discardNewDeviceSet(int deviceSetIndex, uint64_t identity); |
|
//!< What tells one device set from another that has since taken its index: the engine's UID |
|
//!< together with the object's address. Zero when there is no such device set |
|
uint64_t deviceSetIdentity(int deviceSetIndex) const; |
|
friend class NewDeviceSetGuard; |
|
//!< Deletes a channel wherever it has moved to, for callers that held on to it across a wait |
|
void deleteChannelObjectAndWait(uint64_t channelUid); |
|
const void *featureAt(int featureIndex) const; |
|
//!< The UID of the feature or channel at an index, 0 when there is none |
|
uint64_t featureUidAt(int featureIndex) const; |
|
uint64_t channelUidAt(int deviceSetIndex, int channelIndex) const; |
|
void requireNotSelf(int featureIndex, const QString& action) const; |
|
QJsonObject getChannelSettings(int deviceSetIndex, int channelIndex); |
|
QJsonObject patchChannelSettings(int deviceSetIndex, int channelIndex, const QJsonObject& partial); |
|
//!< The property names and types of one settings definition. Used to tell a misspelled key from |
|
//!< a valid one, and to reject a value of the wrong type before it reaches the SWG object |
|
SettingsSchema settingsSchema(const QString& definition); |
|
QString resolveDefinition(const QString& name); //!< Call with m_schemaMutex held |
|
QJsonObject getSpectrumSettings(int deviceSetIndex); |
|
//!< unknownKeys, when given, receives the patch keys the schema does not define |
|
QJsonObject patchSpectrumSettings(int deviceSetIndex, const QJsonObject& partial, QStringList *unknownKeys = nullptr); |
|
//!< Explains an rdsReport that is absent because RDS decoding is switched off, rather than |
|
//!< because nothing has been decoded yet |
|
void addRdsHint(QJsonObject& report, const QString& channelType, int deviceSetIndex, int channelIndex); |
|
QJsonObject getFeatureSettings(int featureIndex); |
|
QJsonObject patchFeatureSettings(int featureIndex, const QJsonObject& partial); |
|
QJsonObject deviceState(int deviceSetIndex, int subsystemIndex, int run); //!< run: 1 start, 0 stop, -1 query |
|
//!< Empty unless the device set's baseband is too narrow for this channel type |
|
QString basebandWarning(int deviceSetIndex, const QString& channelType); |
|
//!< The same for every channel a device set holds |
|
QStringList basebandWarnings(int deviceSetIndex); |
|
QJsonObject featureState(int featureIndex, int run); |
|
QJsonObject presetIdentifier(const QJsonObject& args, int deviceSetIndex, bool forSave); |
|
|
|
// Shared by the intent level tools |
|
QJsonObject channelReport(int deviceSetIndex, int channelIndex); |
|
void postChannelAction(int deviceSetIndex, int channelIndex, const QJsonObject& actions); |
|
//!< doomed: uids of channels the caller is about to remove, which the reused set is not counted as carrying. |
|
//!< profileGain: give a device set this creates the fixed receiver gain profile; false when the gain is about to be measured |
|
QJsonObject pickReceiver(const QJsonObject& args, int minBaseband, const QSet<uint64_t>& doomed = QSet<uint64_t>(), bool profileGain = true); |
|
//!< The tune_gain tool: sweeps the gain and applies the best, with the table it measured |
|
QJsonObject tuneGain(const QJsonObject& args); |
|
//!< Sets the main spectrum's reference level and range from what it shows, as the GUI's autoscale button does |
|
void autoscaleSpectrum(int deviceSetIndex); |
|
//!< Turns spectrum scrolling on if it is off, which is what keeps the history the spectrum |
|
//!< history tools read. Returns a note when it did, empty otherwise |
|
QString ensureSpectrumHistory(int deviceSetIndex, double seconds); |
|
//!< The index of a feature of this type, adding one if there is none. Returns whether it was added |
|
int ensureFeature(const QString& featureType, int& featureIndex); |
|
void trackIntentFeature(uint64_t featureUid); |
|
//!< Removes the features listen added that no channel it added still feeds, except one of keepType. |
|
//!< Returns the types of those removed |
|
QStringList reclaimIntentFeatures(const QString& keepType = QString()); |
|
//!< Deletes a feature wherever it has been renumbered to |
|
void deleteFeatureObjectAndWait(uint64_t featureUid); |
|
//!< Whether listen or scan should measure the gain: a device set they created, or a retune to another band |
|
static bool gainWorthTuning(bool reused, double previousCentre, double centre); |
|
void trackIntentChannel(uint64_t channelUid); |
|
void untrackIntentChannel(uint64_t channelUid); |
|
QSet<uint64_t> intentChannels(); |
|
//!< A channel's type id and whether listen or scan added it, for the notes the intent tools leave |
|
struct ChannelNote { uint64_t m_uid; int m_index; QString m_id; bool m_intent; }; |
|
QList<ChannelNote> channelNotes(int deviceSetIndex, const QSet<uint64_t>& except = QSet<uint64_t>()); |
|
//!< Removes the channels listen and scan added to a device set, except keep. Returns the ids of those removed |
|
QStringList reclaimIntentChannels(int deviceSetIndex, const QSet<uint64_t>& keep = QSet<uint64_t>()); |
|
//!< The channel a previous listen added that a new one of this type can retune instead of replacing, or 0. |
|
//!< wanted: how many of the type the mode uses, 2 for a paired mode |
|
uint64_t reusableIntentChannel(int deviceSetIndex, const QString& channelType, int& channelIndex, int wanted = 1); |
|
//!< What a retune of a reused device set did to the channels listen and scan did not add |
|
struct RetuneOutcome |
|
{ |
|
QStringList m_kept; //!< Re-offset so that they stay on the frequency they had |
|
QStringList m_removed; //!< Audio demodulators the new baseband could not hold, which would only have made noise |
|
QStringList m_stranded; //!< Left where they were: not audio, or the baseband unknown |
|
}; |
|
RetuneOutcome retuneOtherChannels(int deviceSetIndex, double previousCentre, double centre, int baseband); |
|
//!< What listen and scan tell the caller about the rest of the device set once their own channels are in |
|
QStringList intentNotes(int deviceSetIndex, const QSet<uint64_t>& added, const QStringList& reclaimed, |
|
bool reused, double previousCentre, double centre, const RetuneOutcome& outcome); |
|
//!< Channel type ids for a direction, independent of how list_channel_types formats them |
|
QStringList channelTypeIds(int direction); |
|
//!< Where a channel is now. The intent tools sleep for many seconds without holding the |
|
//!< protocol mutex, and a concurrent request that deletes a lower numbered channel |
|
//!< renumbers everything above it, so their indices have to be resolved again before use. |
|
void relocateChannel(uint64_t channelUid, int& deviceSetIndex, int& channelIndex, const QString& what); |
|
|
|
void loadYamlDefinitions(); //!< Call with m_schemaMutex held |
|
}; |
|
|
|
#endif // INCLUDE_FEATURE_MCPTOOLS_H_
|
|
|