Add integration startup service and fix Doxygen (fw 0.8.1).

Replace the services stub with IntegrationService for boot preset recall and tune orchestration, persist last preset in NVS, and remove invalid @return tags that broke CI on T4 metadata headers. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 00:17:13 +02:00
parent 0fc714e431
commit d13012ce4b
24 changed files with 858 additions and 92 deletions
@@ -38,7 +38,6 @@ public:
     * @brief    reset — discard accumulated DLS segments.
     *
     * @dname    reset
-     * @return   n/a
     * @pubstate clears buffer and segment flags.
     *
     * @author   Michele Bigi
@@ -53,7 +52,6 @@ public:
     * @param    segmentIndex  Zero-based segment index from the chip.
     * @param    segmentCount  Total segments advertised for this label.
     * @param    payload       Raw UTF-8 bytes for this segment.
-     * @return   n/a
     * @pubstate copies payload into buffer_ at the computed offset.
     *
     * @author   Michele Bigi
@@ -20,6 +20,7 @@
 #include "core/StoreError.hpp"
 #include "core/WifiCredentials.hpp"

+#include <cstdint>
 #include <expected>
 #include <string>
 #include <string_view>
@@ -157,6 +158,58 @@ public:
     */
    [[nodiscard]] virtual std::expected<void, StoreError>
    clearStationList() = 0;
+
+    /**
+     * @brief    hasLastPresetIndex — check whether a last-recalled preset exists.
+     *
+     * @dname    hasLastPresetIndex
+     * @return   true when loadLastPresetIndex would succeed.
+     * @pubstate reads backing storage via implementation.
+     *
+     * @author   Michele Bigi
+     * @date     2026-07-06
+     */
+    [[nodiscard]] virtual bool hasLastPresetIndex() const = 0;
+
+    /**
+     * @brief    saveLastPresetIndex — persist the last recalled preset index.
+     *
+     * @dname    saveLastPresetIndex
+     * @param    index  Zero-based preset list position (0–19).
+     * @return   Ok on success, or StoreError::IoFailed.
+     * @pubstate writes backing storage via implementation.
+     *
+     * @author   Michele Bigi
+     * @date     2026-07-06
+     */
+    [[nodiscard]] virtual std::expected<void, StoreError>
+    saveLastPresetIndex(std::uint8_t index) = 0;
+
+    /**
+     * @brief    loadLastPresetIndex — read the last recalled preset index.
+     *
+     * @dname    loadLastPresetIndex
+     * @return   Preset index on success, or StoreError.
+     * @pubstate reads backing storage via implementation.
+     *
+     * @author   Michele Bigi
+     * @date     2026-07-06
+     */
+    [[nodiscard]] virtual std::expected<std::uint8_t, StoreError>
+    loadLastPresetIndex() const = 0;
+
+    /**
+     * @brief    clearLastPresetIndex — erase the last-recalled preset marker.
+     *
+     * @dname    clearLastPresetIndex
+     * @return   Ok on success, or StoreError::IoFailed.
+     * @pubstate clears backing storage via implementation.
+     *
+     * @author   Michele Bigi
+     * @date     2026-07-06
+     */
+    [[nodiscard]] virtual std::expected<void, StoreError>
+    clearLastPresetIndex() = 0;
 };

 } // namespace core
@@ -0,0 +1,34 @@
+/**
+ * @file    IntegrationError.hpp
+ * @brief   Typed errors for application integration flows.
+ *
+ * DigiRadio firmware — https://github.com/manvalan/DigiRadio
+ *
+ * Copyright 2026 Michele Bigi
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * @author  Michele Bigi
+ * @date    2026-07-06
+ */
+#pragma once
+
+namespace core {
+
+/**
+ * @brief    IntegrationError — failure causes for preset recall orchestration.
+ *
+ * @dname    IntegrationError
+ * @return   n/a (type)
+ * @pubstate n/a
+ *
+ * @author   Michele Bigi
+ * @date     2026-07-06
+ */
+enum class IntegrationError {
+    StoreFailed,    ///< NVS load/save failed during startup or recall.
+    PresetNotFound, ///< Preset index out of range.
+    TuneFailed,     ///< Tuner could not recall the preset target.
+    AudioFailed,    ///< ADAU1701 profile could not be applied.
+};
+
+} // namespace core
@@ -36,7 +36,6 @@ public:
     * @brief    reset — clear accumulated PS and radiotext.
     *
     * @dname    reset
-     * @return   n/a
     * @pubstate clears internal buffers.
     *
     * @author   Michele Bigi
@@ -52,7 +51,6 @@ public:
     * @param    blockB  RDS block B (group type and address).
     * @param    blockC  RDS block C (text payload).
     * @param    blockD  RDS block D (text payload for RT).
-     * @return   n/a
     * @pubstate updates PS/RT buffers for group types 0A and 2A.
     *
     * @author   Michele Bigi
@@ -104,3 +104,19 @@ add_test(NAME bt1035_at_test COMMAND bt1035_at_test)
 add_executable(broadcast_metadata_test broadcast_metadata_test.cpp)
 target_link_libraries(broadcast_metadata_test PRIVATE digiradio_core)
 add_test(NAME broadcast_metadata_test COMMAND broadcast_metadata_test)
+
+add_executable(integration_service_test integration_service_test.cpp)
+target_include_directories(integration_service_test PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/integration/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/station/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/tuner/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/audio/include"
+)
+target_sources(integration_service_test PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/integration/src/IntegrationService.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/station/src/StationService.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/tuner/src/TunerService.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../services/audio/src/AudioService.cpp"
+)
+target_link_libraries(integration_service_test PRIVATE digiradio_core)
+add_test(NAME integration_service_test COMMAND integration_service_test)
@@ -0,0 +1,286 @@
+/**
+ * @file    integration_service_test.cpp
+ * @brief   Host tests for IntegrationService preset recall flow.
+ *
+ * DigiRadio firmware — https://github.com/manvalan/DigiRadio
+ *
+ * Copyright 2026 Michele Bigi
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * @author  Michele Bigi
+ * @date    2026-07-06
+ */
+
+#include "audio/AudioService.hpp"
+#include "core/FrequencyKHz.hpp"
+#include "core/IDsp.hpp"
+#include "core/ISecureStore.hpp"
+#include "core/StationName.hpp"
+#include "core/TunerBand.hpp"
+#include "integration/IntegrationService.hpp"
+#include "station/StationService.hpp"
+#include "tuner/TunerService.hpp"
+
+#include <cstdlib>
+#include <iostream>
+#include <optional>
+#include <string>
+
+namespace {
+
+class FakeDsp final : public core::IDsp {
+public:
+    std::size_t applyProfileCalls{0U};
+
+    [[nodiscard]] std::expected<void, core::DspError> applyProfile(
+        const core::AudioProfile&) override
+    {
+        ++applyProfileCalls;
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::DspError> applyMixer(
+        const core::MixerState&) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::DspError> applyEq(
+        const core::EqProfile&) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::DspError> setInputVolume(
+        core::MixSource, core::GainDb, core::GainDb) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::DspError> setMasterVolume(
+        core::GainDb, core::GainDb) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::DspError> setEqBand(
+        core::EqBandIndex, core::GainDb, core::FrequencyHz, float) override
+    {
+        return {};
+    }
+};
+
+class TrackingTuner final : public core::ITuner {
+public:
+    bool tunedFm{false};
+
+    [[nodiscard]] std::expected<void, core::TunerError> boot(
+        core::TunerBand) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<core::TunerBand, core::TunerError> currentBand()
+        const override
+    {
+        return core::TunerBand::Fm;
+    }
+
+    [[nodiscard]] std::expected<core::TunerStatus, core::TunerError> readStatus()
+        override
+    {
+        core::TunerStatus status = {};
+        status.booted = true;
+        status.band = core::TunerBand::Fm;
+        status.locked = true;
+        status.volume = 40;
+        return status;
+    }
+
+    [[nodiscard]] std::expected<void, core::TunerError> tuneDab(
+        std::uint8_t) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::TunerError> tuneFm(
+        core::FrequencyKHz) override
+    {
+        tunedFm = true;
+        return {};
+    }
+
+    [[nodiscard]] std::expected<core::FrequencyKHz, core::TunerError> seekFm(
+        core::SeekDirection) override
+    {
+        return std::unexpected(core::TunerError::WrongBand);
+    }
+
+    [[nodiscard]] std::expected<std::vector<core::TunerServiceEntry>,
+                                core::TunerError>
+    listDabServices() override
+    {
+        return std::vector<core::TunerServiceEntry>{};
+    }
+
+    [[nodiscard]] std::expected<void, core::TunerError> playDabService(
+        std::uint32_t, std::uint32_t) override
+    {
+        return {};
+    }
+
+    [[nodiscard]] std::expected<void, core::TunerError> setVolume(
+        std::uint8_t) override
+    {
+        return {};
+    }
+};
+
+class FakeSecureStore final : public core::ISecureStore {
+public:
+    [[nodiscard]] bool hasWifiCredentials() const override
+    {
+        return false;
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> saveWifiCredentials(
+        const core::WifiCredentials&) override
+    {
+        return std::unexpected(core::StoreError::IoFailed);
+    }
+
+    [[nodiscard]] std::expected<core::WifiCredentials, core::StoreError>
+    loadWifiCredentials() const override
+    {
+        return std::unexpected(core::StoreError::NotFound);
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> clearWifiCredentials()
+        override
+    {
+        return {};
+    }
+
+    [[nodiscard]] bool hasStationList() const override
+    {
+        return stationJson_.has_value();
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> saveStationListJson(
+        std::string_view json) override
+    {
+        stationJson_ = std::string(json);
+        return {};
+    }
+
+    [[nodiscard]] std::expected<std::string, core::StoreError>
+    loadStationListJson() const override
+    {
+        if (!stationJson_) {
+            return std::unexpected(core::StoreError::NotFound);
+        }
+        return *stationJson_;
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> clearStationList()
+        override
+    {
+        stationJson_.reset();
+        return {};
+    }
+
+    [[nodiscard]] bool hasLastPresetIndex() const override
+    {
+        return lastPresetIndex_.has_value();
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> saveLastPresetIndex(
+        std::uint8_t index) override
+    {
+        lastPresetIndex_ = index;
+        return {};
+    }
+
+    [[nodiscard]] std::expected<std::uint8_t, core::StoreError>
+    loadLastPresetIndex() const override
+    {
+        if (!lastPresetIndex_) {
+            return std::unexpected(core::StoreError::NotFound);
+        }
+        return *lastPresetIndex_;
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> clearLastPresetIndex()
+        override
+    {
+        lastPresetIndex_.reset();
+        return {};
+    }
+
+private:
+    std::optional<std::string> stationJson_;
+    std::optional<std::uint8_t> lastPresetIndex_;
+};
+
+[[nodiscard]] core::Station makeFmStation(const char* name, std::uint32_t khz)
+{
+    return core::Station(
+        *core::StationName::tryFrom(name),
+        core::TunerBand::Fm,
+        0U,
+        std::nullopt,
+        std::nullopt,
+        *core::FrequencyKHz::tryFromKhz(khz),
+        std::nullopt);
+}
+
+[[nodiscard]] int runRecallPresetTest()
+{
+    FakeSecureStore store;
+    TrackingTuner tunerHw;
+    FakeDsp dsp;
+    tuner::TunerService tunerService(tunerHw);
+    audio::AudioService audioService(dsp, nullptr);
+    station::StationService stationService(store, tunerService);
+    integration::IntegrationService integration(
+        store, tunerService, audioService, stationService);
+
+    if (auto added = stationService.add(makeFmStation("Jazz", 101500U)); !added) {
+        std::cerr << "add preset failed\n";
+        return EXIT_FAILURE;
+    }
+
+    if (auto recalled = integration.recallPreset(0U); !recalled) {
+        std::cerr << "recallPreset failed\n";
+        return EXIT_FAILURE;
+    }
+    if (!tunerHw.tunedFm || dsp.applyProfileCalls == 0U
+        || !store.hasLastPresetIndex()) {
+        std::cerr << "recallPreset side effects missing\n";
+        return EXIT_FAILURE;
+    }
+
+    tunerHw.tunedFm = false;
+    dsp.applyProfileCalls = 0U;
+    integration::IntegrationService rebooted(
+        store, tunerService, audioService, stationService);
+    if (auto started = rebooted.startup(); !started) {
+        std::cerr << "startup failed\n";
+        return EXIT_FAILURE;
+    }
+    if (!tunerHw.tunedFm || dsp.applyProfileCalls == 0U) {
+        std::cerr << "startup did not recall last preset\n";
+        return EXIT_FAILURE;
+    }
+    return EXIT_SUCCESS;
+}
+
+} // namespace
+
+int main()
+{
+    if (runRecallPresetTest() != EXIT_SUCCESS) {
+        return EXIT_FAILURE;
+    }
+    return EXIT_SUCCESS;
+}
@@ -143,8 +143,37 @@ public:
        return {};
    }

+    [[nodiscard]] bool hasLastPresetIndex() const override
+    {
+        return lastPresetIndex_.has_value();
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> saveLastPresetIndex(
+        std::uint8_t index) override
+    {
+        lastPresetIndex_ = index;
+        return {};
+    }
+
+    [[nodiscard]] std::expected<std::uint8_t, core::StoreError>
+    loadLastPresetIndex() const override
+    {
+        if (!lastPresetIndex_) {
+            return std::unexpected(core::StoreError::NotFound);
+        }
+        return *lastPresetIndex_;
+    }
+
+    [[nodiscard]] std::expected<void, core::StoreError> clearLastPresetIndex()
+        override
+    {
+        lastPresetIndex_.reset();
+        return {};
+    }
+
 private:
    std::optional<std::string> stationJson_;
+    std::optional<std::uint8_t> lastPresetIndex_;
 };

 [[nodiscard]] core::Station makeFmStation(const char* name, std::uint32_t khz)