diff --git a/adafruit_fruitjam/__init__.py b/adafruit_fruitjam/__init__.py index 51af6e6..35bde3e 100644 --- a/adafruit_fruitjam/__init__.py +++ b/adafruit_fruitjam/__init__.py @@ -195,6 +195,8 @@ class FruitJam(PortalBase): self.play_file = self.peripherals.play_file self.play_mp3_file = self.peripherals.play_mp3_file self.stop_play = self.peripherals.stop_play + self.volume = self.peripherals.volume + self.audio_output = self.peripherals.audio_output self.image_converter_url = self.network.image_converter_url self.wget = self.network.wget @@ -246,6 +248,26 @@ class FruitJam(PortalBase): gc.collect() + def sync_time(self, **kwargs): + """Set the system RTC via NTP using this FruitJam's Network. + + This is a convenience wrapper for ``self.network.sync_time(...)``. + + :param str server: Override NTP host (defaults to ``NTP_SERVER`` or + ``"pool.ntp.org"`` if unset). (Pass via ``server=...`` in kwargs.) + :param float tz_offset: Override hours from UTC (defaults to ``NTP_TZ``; + ``NTP_DST`` is still added). (Pass via ``tz_offset=...``.) + :param dict tuning: Advanced options dict (optional). Supported keys: + ``timeout`` (float, socket timeout seconds; defaults to ``NTP_TIMEOUT`` or 5.0), + ``cache_seconds`` (int; defaults to ``NTP_CACHE_SECONDS`` or 0), + ``require_year`` (int; defaults to ``NTP_REQUIRE_YEAR`` or 2022). + (Pass via ``tuning={...}``.) + + :returns: Synced time + :rtype: time.struct_time + """ + return self.network.sync_time(**kwargs) + def set_caption(self, caption_text, caption_position, caption_color): """A caption. Requires setting ``caption_font`` in init! diff --git a/adafruit_fruitjam/network.py b/adafruit_fruitjam/network.py index 8c73b98..fc349ac 100644 --- a/adafruit_fruitjam/network.py +++ b/adafruit_fruitjam/network.py @@ -1,5 +1,6 @@ # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams, written for Adafruit Industries # SPDX-FileCopyrightText: 2025 Tim Cocks, written for Adafruit Industries +# SPDX-FileCopyrightText: 2025 Mikey Sklar, written for Adafruit Industries # # SPDX-License-Identifier: Unlicense """ @@ -25,9 +26,14 @@ Implementation Notes """ import gc +import os +import time +import adafruit_connection_manager as acm +import adafruit_ntp import microcontroller import neopixel +import rtc from adafruit_portalbase.network import ( CONTENT_IMAGE, CONTENT_JSON, @@ -209,3 +215,133 @@ class Network(NetworkBase): gc.collect() return filename, position + + def sync_time(self, server=None, tz_offset=None, tuning=None): + """ + Set the system RTC via NTP using this Network's Wi-Fi connection. + + Reads optional settings from settings.toml: + + NTP_SERVER – NTP host (default: "pool.ntp.org") + NTP_TZ – timezone offset in hours (float, default: 0) + NTP_DST – extra offset for daylight saving (0=no, 1=yes; default: 0) + NTP_INTERVAL – re-sync interval in seconds (default: 3600, not used internally) + + NTP_TIMEOUT – socket timeout per attempt (seconds, default: 5.0) + NTP_CACHE_SECONDS – cache results, 0 = always fetch fresh (default: 0) + NTP_REQUIRE_YEAR – minimum acceptable year (default: 2022) + + NTP_RETRIES – number of NTP fetch attempts on timeout (default: 8) + NTP_DELAY_S – delay between retries in seconds (default: 1.0) + + Keyword args: + server (str) – override NTP_SERVER + tz_offset (float) – override NTP_TZ (+ NTP_DST still applied) + tuning (dict) – override tuning knobs, e.g.: + { + "timeout": 5.0, + "cache_seconds": 0, + "require_year": 2022, + "retries": 8, + "retry_delay": 1.0, + } + + Returns: + time.struct_time + """ + # Ensure Wi-Fi up + self.connect() + + # Socket pool + pool = acm.get_radio_socketpool(self._wifi.esp) + + # Settings & overrides + server = server or os.getenv("NTP_SERVER") or "pool.ntp.org" + tz = tz_offset if tz_offset is not None else _combined_tz_offset(0.0) + t = tuning or {} + + timeout = float(t.get("timeout", _get_float_env("NTP_TIMEOUT", 5.0))) + cache_seconds = int(t.get("cache_seconds", _get_int_env("NTP_CACHE_SECONDS", 0))) + require_year = int(t.get("require_year", _get_int_env("NTP_REQUIRE_YEAR", 2022))) + ntp_retries = int(t.get("retries", _get_int_env("NTP_RETRIES", 8))) + ntp_delay_s = float(t.get("retry_delay", _get_float_env("NTP_DELAY_S", 1.0))) + + # NTP client + ntp = adafruit_ntp.NTP( + pool, + server=server, + tz_offset=tz, + socket_timeout=timeout, + cache_seconds=cache_seconds, + ) + + # Attempt fetch (retries on timeout) + now = _ntp_get_datetime( + ntp, + connect_cb=self.connect, + retries=ntp_retries, + delay_s=ntp_delay_s, + debug=getattr(self, "_debug", False), + ) + + # Sanity check & commit + if now.tm_year < require_year: + raise RuntimeError("NTP returned an unexpected year; not setting RTC") + + rtc.RTC().datetime = now + return now + + +# ---- Internal helpers to keep sync_time() small and Ruff-friendly ---- + + +def _get_float_env(name, default): + v = os.getenv(name) + try: + return float(v) if v not in {None, ""} else float(default) + except Exception: + return float(default) + + +def _get_int_env(name, default): + v = os.getenv(name) + if v in {None, ""}: + return int(default) + try: + return int(v) + except Exception: + try: + return int(float(v)) # tolerate "5.0" + except Exception: + return int(default) + + +def _combined_tz_offset(base_default): + """Return tz offset hours including DST via env (NTP_TZ + NTP_DST).""" + tz = _get_float_env("NTP_TZ", base_default) + dst = _get_float_env("NTP_DST", 0) + return tz + dst + + +def _ntp_get_datetime(ntp, connect_cb, retries, delay_s, debug=False): + """Fetch ntp.datetime with limited retries on timeout; re-connect between tries.""" + for i in range(retries): + last_exc = None + try: + return ntp.datetime # struct_time + except OSError as e: + last_exc = e + is_timeout = (getattr(e, "errno", None) == 116) or ("ETIMEDOUT" in str(e)) + if not is_timeout: + break + if debug: + print(f"NTP timeout, attempt {i + 1}/{retries}") + connect_cb() # re-assert Wi-Fi using existing policy + time.sleep(delay_s) + continue + except Exception as e: + last_exc = e + break + if last_exc: + raise last_exc + raise RuntimeError("NTP sync failed") diff --git a/adafruit_fruitjam/peripherals.py b/adafruit_fruitjam/peripherals.py index e0797d2..5b0473c 100644 --- a/adafruit_fruitjam/peripherals.py +++ b/adafruit_fruitjam/peripherals.py @@ -40,6 +40,7 @@ import framebufferio import picodvi import storage import supervisor +from adafruit_simplemath import map_range from digitalio import DigitalInOut, Direction, Pull from neopixel import NeoPixel @@ -133,13 +134,16 @@ def get_display_config(): class Peripherals: """Peripherals Helper Class for the FruitJam Library + :param audio_output: The audio output interface to use 'speaker' or 'headphone' + :param safe_volume_limit: The maximum volume allowed for the audio output. Default is 15 + Using higher values can damage some speakers, change at your own risk. Attributes: neopixels (NeoPxiels): The NeoPixels on the Fruit Jam board. See https://circuitpython.readthedocs.io/projects/neopixel/en/latest/api.html """ - def __init__(self): + def __init__(self, audio_output="headphone", safe_volume_limit=12): self.neopixels = NeoPixel(board.NEOPIXEL, 5) self._buttons = [] @@ -155,11 +159,14 @@ class Peripherals: # set sample rate & bit depth self._dac.configure_clocks(sample_rate=11030, bit_depth=16) - # use headphones - self._dac.headphone_output = True - self._dac.headphone_volume = -15 # dB - + self._audio_output = audio_output + self.audio_output = audio_output self._audio = audiobusio.I2SOut(board.I2S_BCLK, board.I2S_WS, board.I2S_DIN) + if safe_volume_limit < 1 or safe_volume_limit > 20: + raise ValueError("safe_volume_limit must be between 1 and 20") + self.safe_volume_limit = safe_volume_limit + self._volume = 7 + self._apply_volume() self._sd_mounted = False sd_pins_in_use = False @@ -266,3 +273,61 @@ class Peripherals: self.audio.stop() if self.wavfile is not None: self.wavfile.close() + + @property + def volume(self) -> int: + """ + The volume level of the Fruit Jam audio output. Valid values are 1-20. + """ + return self._volume + + @volume.setter + def volume(self, volume_level: int) -> None: + """ + :param volume_level: new volume level 1-20 + :return: None + """ + if not (1 <= volume_level <= 20): + raise ValueError("Volume level must be between 1 and 20") + + if volume_level > self.safe_volume_limit: + raise ValueError( + f"""Volume level must be less than or equal to +safe_volume_limit: {self.safe_volume_limit}. Using higher values could damage speakers. +To override this limitation set a larger value than {self.safe_volume_limit} +for the safe_volume_limit with the constructor or property.""" + ) + + self._volume = volume_level + self._apply_volume() + + @property + def audio_output(self) -> str: + """ + The audio output interface. 'speaker' or 'headphone' + :return: + """ + return self._audio_output + + @audio_output.setter + def audio_output(self, audio_output: str) -> None: + """ + + :param audio_output: The audio interface to use 'speaker' or 'headphone'. + :return: None + """ + if audio_output == "headphone": + self._dac.headphone_output = True + self._dac.speaker_output = False + elif audio_output == "speaker": + self._dac.headphone_output = False + self._dac.speaker_output = True + else: + raise ValueError("audio_output must be either 'headphone' or 'speaker'") + + def _apply_volume(self) -> None: + """ + Map the basic volume level to a db value and set it on the DAC. + """ + db_val = map_range(self._volume, 1, 20, -63, 23) + self._dac.dac_volume = db_val diff --git a/docs/conf.py b/docs/conf.py index 5afc3cc..f51f557 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,9 @@ autodoc_mock_imports = [ "audiocore", "storage", "terminalio", + "adafruit_connection_manager", + "adafruit_ntp", + "rtc", ] autodoc_preserve_defaults = True diff --git a/examples/fruitjam_headphone.py b/examples/fruitjam_headphone.py index c5d3a94..decd1e5 100644 --- a/examples/fruitjam_headphone.py +++ b/examples/fruitjam_headphone.py @@ -5,21 +5,16 @@ import time import adafruit_fruitjam -pobj = adafruit_fruitjam.peripherals.Peripherals() -dac = pobj.dac # use Fruit Jam's codec - -# Route once for headphones -dac.headphone_output = True -dac.speaker_output = False +pobj = adafruit_fruitjam.peripherals.Peripherals(audio_output="headphone") FILES = ["beep.wav", "dip.wav", "rise.wav"] -VOLUMES_DB = [12, 6, 0, -6, -12] +VOLUMES = [5, 7, 10, 11, 12] while True: print("\n=== Headphones Test ===") - for vol in VOLUMES_DB: - dac.dac_volume = vol - print(f"Headphones volume: {vol} dB") + for vol in VOLUMES: + pobj.volume = vol + print(f"Headphones volume: {vol}") for f in FILES: print(f" -> {f}") pobj.play_file(f) diff --git a/examples/fruitjam_ntp_settings.toml b/examples/fruitjam_ntp_settings.toml new file mode 100644 index 0000000..4cd2313 --- /dev/null +++ b/examples/fruitjam_ntp_settings.toml @@ -0,0 +1,33 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025 Mikey Sklar for Adafruit Industries +# +# SPDX-License-Identifier: MIT +# Wi-Fi credentials +CIRCUITPY_WIFI_SSID = "YourSSID" +CIRCUITPY_WIFI_PASSWORD = "YourPassword" + +# NTP settings +# Common UTC offsets (hours): +# 0 UTC / Zulu +# 1 CET (Central Europe) +# 2 EET (Eastern Europe) +# 3 FET (Further Eastern Europe) +# -5 EST (Eastern US) +# -6 CST (Central US) +# -7 MST (Mountain US) +# -8 PST (Pacific US) +# -9 AKST (Alaska) +# -10 HST (Hawaii, no DST) + +NTP_SERVER = "pool.ntp.org" # NTP host (default pool.ntp.org) +NTP_TZ = -5 # timezone offset in hours +NTP_DST = 1 # daylight saving (0=no, 1=yes) +NTP_INTERVAL = 3600 # re-sync interval (seconds) + +# Optional tuning +NTP_TIMEOUT = "1.0" # socket timeout in seconds +NTP_CACHE_SECONDS = 0 # cache results (0 = always fetch) +NTP_REQUIRE_YEAR = 2022 # sanity check minimum year + +# Retries +NTP_RETRIES = 8 # number of NTP fetch attempts +NTP_DELAY_S = "1.5" # delay between attempts (seconds) diff --git a/examples/fruitjam_speaker.py b/examples/fruitjam_speaker.py index 02e75fa..64ec015 100644 --- a/examples/fruitjam_speaker.py +++ b/examples/fruitjam_speaker.py @@ -5,21 +5,16 @@ import time import adafruit_fruitjam -pobj = adafruit_fruitjam.peripherals.Peripherals() -dac = pobj.dac # use Fruit Jam's codec - -# Route once for speaker -dac.headphone_output = False -dac.speaker_output = True +pobj = adafruit_fruitjam.peripherals.Peripherals(audio_output="speaker") FILES = ["beep.wav", "dip.wav", "rise.wav"] -VOLUMES_DB = [12, 6, 0, -6, -12] +VOLUMES = [5, 7, 10, 11, 12] while True: print("\n=== Speaker Test ===") - for vol in VOLUMES_DB: - dac.dac_volume = vol - print(f"Speaker volume: {vol} dB") + for vol in VOLUMES: + pobj.volume = vol + print(f"Speaker volume: {vol}") for f in FILES: print(f" -> {f}") pobj.play_file(f) diff --git a/examples/fruitjam_synthio_speaker.py b/examples/fruitjam_synthio_speaker.py new file mode 100644 index 0000000..a44ce28 --- /dev/null +++ b/examples/fruitjam_synthio_speaker.py @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025 Tim Cocks for Adafruit Industries +# +# SPDX-License-Identifier: MIT +import time + +import synthio + +import adafruit_fruitjam + +pobj = adafruit_fruitjam.peripherals.Peripherals(audio_output="headphone") + +synth = synthio.Synthesizer(sample_rate=44100) +pobj.audio.play(synth) +VOLUMES = [5, 7, 10, 11, 12] +C_major_scale = [60, 62, 64, 65, 67, 69, 71, 72, 71, 69, 67, 65, 64, 62, 60] +while True: + print("\n=== Synthio Test ===") + for vol in VOLUMES: + pobj.volume = vol + print(f"Volume: {vol}") + for note in C_major_scale: + synth.press(note) + time.sleep(0.1) + synth.release(note) + time.sleep(0.05) + + time.sleep(1.0) diff --git a/examples/fruitjam_time_sync.py b/examples/fruitjam_time_sync.py new file mode 100644 index 0000000..08a6af5 --- /dev/null +++ b/examples/fruitjam_time_sync.py @@ -0,0 +1,11 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025 Mikey Sklar for Adafruit Industries +# +# SPDX-License-Identifier: MIT +import time + +from adafruit_fruitjam import FruitJam + +fj = FruitJam() +now = fj.sync_time() +print("RTC set:", now) +print("Localtime:", time.localtime()) diff --git a/requirements.txt b/requirements.txt index d26fdd0..bd4358c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -13,3 +13,6 @@ adafruit-circuitpython-requests adafruit-circuitpython-bitmap-font adafruit-circuitpython-display-text adafruit-circuitpython-sd +adafruit-circuitpython-ntp +adafruit-circuitpython-connectionmanager +adafruit-circuitpython-simplemath