{"id":1189,"date":"2026-03-07T12:38:12","date_gmt":"2026-03-07T17:38:12","guid":{"rendered":"https:\/\/scootercam.net\/blog\/?p=1189"},"modified":"2026-03-07T12:38:13","modified_gmt":"2026-03-07T17:38:13","slug":"admin-guide","status":"publish","type":"post","link":"https:\/\/scootercam.net\/blog\/admin-guide\/","title":{"rendered":"Admin guide"},"content":{"rendered":"\n

Contents<\/strong><\/p>\n\n\n\n

    \n
  1. System Overview<\/a>\n
      \n
    1. Infrastructure at a Glance<\/a><\/li>\n\n\n\n
    2. Key Directories<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
    3. Configuration File<\/a>\n
        \n
      1. Config Blocks<\/a><\/li>\n\n\n\n
      2. API Credentials<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
      3. Cron Jobs<\/a>\n
          \n
        1. Tempest Weather Cron<\/a><\/li>\n\n\n\n
        2. Moon Data Cron<\/a><\/li>\n\n\n\n
        3. Camera \/ Timelapse Cron<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
        4. Cache Files<\/a><\/li>\n\n\n\n
        5. PHP Classes<\/a>\n
            \n
          1. ScooterCam_Tempest<\/a><\/li>\n\n\n\n
          2. ScooterCam_Sunset_Predictor<\/a><\/li>\n\n\n\n
          3. ScooterCam_Moonset_Predictor<\/a><\/li>\n\n\n\n
          4. ScooterCam_SunMoon_Display<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
          5. Display Widgets<\/a>\n
              \n
            1. Alert Banner<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
            2. Weather Alert System<\/a><\/li>\n\n\n\n
            3. Wind Rose Data Accumulator<\/a><\/li>\n\n\n\n
            4. Moon & Sunset Scoring<\/a>\n
                \n
              1. Sunset Score Factors<\/a><\/li>\n\n\n\n
              2. Notable Moonset Criteria<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
              3. Troubleshooting<\/a>\n
                  \n
                1. Common Issues<\/a><\/li>\n\n\n\n
                2. Checking Cron Health<\/a><\/li>\n\n\n\n
                3. Checking Cache File Health<\/a><\/li>\n\n\n\n
                4. Log Files<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
                5. Notes for Future Administrators<\/a>\n
                    \n
                  1. Most Likely Things to Need Attention<\/a><\/li>\n\n\n\n
                  2. What NOT to Change<\/a><\/li>\n<\/ol>\n<\/li>\n<\/ol>\n\n\n\n
                    \n\n\n\n

                    1. System Overview<\/h2>\n\n\n\n

                    ScooterCam is a custom PHP-based weather monitoring and sunset photography system serving the Lake Michigan shoreline between South Haven and Saugatuck, Michigan. It is hosted on GlowHost shared hosting with Cloudflare as the DNS and CDN layer.<\/p>\n\n\n\n

                    The system consists of a Raspberry Pi 5 at the shoreline running a Python scheduler (camctl), two Reolink IP cameras, a Tempest weather station, and a PHP web application on the server. A WordPress installation runs separately in the \/blog\/<\/code> subdirectory and is largely independent of the main application.<\/p>\n\n\n\n

                    1.1 Infrastructure at a Glance<\/h3>\n\n\n\n
                    Component<\/th>Details<\/th><\/tr><\/thead>
                    Web host<\/strong><\/td>GlowHost shared hosting<\/td><\/tr>
                    CDN \/ DNS<\/strong><\/td>Cloudflare<\/td><\/tr>
                    Server path<\/strong><\/td>\/home\/scooterc\/public_html<\/code><\/td><\/tr>
                    WordPress<\/strong><\/td>\/home\/scooterc\/public_html\/blog\/<\/code><\/td><\/tr>
                    Pi access<\/strong><\/td>Raspberry Pi Connect (remote) + SSHFS (file mount)<\/td><\/tr>
                    Dev environment<\/strong><\/td>Mac + BBEdit with SSHFS mount<\/td><\/tr>
                    PHP template system<\/strong><\/td>Custom: header.php, footer.php, $page_config<\/td><\/tr>
                    Timezone<\/strong><\/td>America\/Detroit (all timestamps)<\/td><\/tr>
                    Coordinates<\/strong><\/td>42.5593, \u221286.2361 (South Haven\/Saugatuck area)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    1.2 Key Directories<\/h3>\n\n\n\n
                    Path<\/th>Purpose<\/th><\/tr><\/thead>
                    includes\/<\/code><\/td>PHP classes, config, widgets, alert banner<\/td><\/tr>
                    includes\/widgets\/<\/code><\/td>Individual display widgets (chart, pressure, wind rose, etc.)<\/td><\/tr>
                    cache\/<\/code><\/td>All JSON cache files written by cron and API classes<\/td><\/tr>
                    cron\/<\/code><\/td>All cron scripts \u2014 run via server crontab<\/td><\/tr>
                    data\/tempest\/<\/code><\/td>Tempest API response cache (MD5-keyed JSON files)<\/td><\/tr>
                    logs\/<\/code><\/td>Cron output logs<\/td><\/tr>
                    timelapse\/<\/code><\/td>Timelapse video output<\/td><\/tr>
                    live\/<\/code><\/td>Live camera image staging<\/td><\/tr>
                    blog\/<\/code><\/td>WordPress installation (independent)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    2. Configuration File<\/h2>\n\n\n\n

                    All site-wide settings live in a single file: includes\/config.php<\/code>. This file returns a PHP array and is loaded by every page and cron script. Never hardcode credentials or paths anywhere else.<\/p>\n\n\n\n

                    \n

                    includes\/config.php is the single source of truth<\/strong> for all API keys, credentials, paths, and settings. If something stops working, check here first.<\/p>\n<\/blockquote>\n\n\n\n

                    2.1 Config Blocks<\/h3>\n\n\n\n
                    Block<\/th>Purpose<\/th><\/tr><\/thead>
                    tempest<\/code><\/td>Tempest API token, station ID, device ID, cache durations, alert and wind rose cache paths<\/td><\/tr>
                    visual_crossing<\/code><\/td>Visual Crossing API key and location string for 15-day forecast<\/td><\/tr>
                    openweather<\/code><\/td>OpenWeatherMap API key, lat\/lon for marine and moonset weather data<\/td><\/tr>
                    sunmoon<\/code><\/td>All sun\/moon\/sunset scoring config: API keys, home + horizon coordinates, moon data file path, cache expiry<\/td><\/tr>
                    site<\/code><\/td>Site name, tagline, timezone, location name<\/td><\/tr>
                    paths<\/code><\/td>Absolute filesystem paths for cameras, images, timelapse, logs, data directories<\/td><\/tr>
                    periods<\/code><\/td>Time period definitions for timelapse (morning, afternoon, evening, night)<\/td><\/tr>
                    cameras<\/code><\/td>Per-camera configuration: name, display name, enabled flag, capture timing, capabilities<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    2.2 API Credentials<\/h3>\n\n\n\n
                    Service<\/th>Key location<\/th>Notes<\/th><\/tr><\/thead>
                    Tempest WeatherFlow<\/td>config[tempest][token]<\/code><\/td>Personal use token \u2014 does not expire<\/td><\/tr>
                    Visual Crossing<\/td>config[visual_crossing][api_key]<\/code><\/td>15-day forecast<\/td><\/tr>
                    OpenWeatherMap<\/td>config[openweather][api_key]<\/code><\/td>Used by sunset + moonset scoring<\/td><\/tr>
                    RapidAPI (moon-phase)<\/td>config[sunmoon][moon_api_key]<\/code><\/td>Called only<\/strong> by cron \u2014 never at page load<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                    \n

                    \u26a0\ufe0f The RapidAPI moon-phase key must never be called from a page load.<\/strong> In March 2026 a caching failure caused 3,200% quota overrun and significant unexpected charges. Moon data is now fetched exclusively by cron\/moon-cache-cron.php<\/code> once daily.<\/p>\n<\/blockquote>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    3. Cron Jobs<\/h2>\n\n\n\n

                    All time-sensitive data is populated by cron scripts, never at page load time. This is critical for performance on shared hosting. Run crontab -l<\/code> to verify all entries are active.<\/p>\n\n\n\n

                    3.1 Tempest Weather Cron<\/h3>\n\n\n\n

                    File:<\/strong> cron\/tempest-cache-cron.php<\/code>
                    Schedule:<\/strong> Every 5 minutes \u2014 *\/5 * * * *<\/code>
                    Log:<\/strong> logs\/tempest-cron.log<\/code><\/p>\n\n\n\n

                    This is the main data cron. It runs six steps in sequence, each reusing data from earlier steps to avoid redundant API calls:<\/p>\n\n\n\n

                    Step<\/th>What it does<\/th>Output<\/th><\/tr><\/thead>
                    1<\/strong><\/td>Fetch current conditions from Tempest station API<\/td>$current observation array<\/td><\/tr>
                    2<\/strong><\/td>Fetch 10-day daily forecast<\/td>data\/tempest\/ cache files<\/td><\/tr>
                    3<\/strong><\/td>Fetch 24-hour hourly forecast<\/td>data\/tempest\/ cache files<\/td><\/tr>
                    4<\/strong><\/td>Fetch 24 hours of historical observations<\/td>$historical array<\/td><\/tr>
                    5<\/strong><\/td>Derive weather alerts from $current<\/td>cache\/sc_alerts.json<\/td><\/tr>
                    6<\/strong><\/td>Append wind direction\/speed to rolling 30-day log<\/td>cache\/sc_wind_rose.json<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    3.2 Moon Data Cron<\/h3>\n\n\n\n

                    File:<\/strong> cron\/moon-cache-cron.php<\/code>
                    Schedule:<\/strong> Once daily at 1 AM \u2014 0 1 * * *<\/code>
                    Log:<\/strong> logs\/moon-cron.log<\/code><\/p>\n\n\n\n

                    Fetches moon phase data from RapidAPI (moon-phase.p.rapidapi.com<\/code>) and sun data via PHP’s built-in date_sun_info()<\/code>. Writes a normalized JSON file to cache\/sc_moon_data.json<\/code>. All moon and sun display on the site reads this file \u2014 zero API calls happen at page load.<\/p>\n\n\n\n

                    A lock file (sys_get_temp_dir()\/sc_moon_cron.lock<\/code>) prevents duplicate runs within the same hour in case of crontab misconfiguration. If the cache file is more than 36 hours old, a warning is written to the PHP error log; the old data continues to display rather than showing an error.<\/p>\n\n\n\n

                    3.3 Camera \/ Timelapse Cron (Pi-side)<\/h3>\n\n\n\n

                    The Raspberry Pi 5 runs its own Python scheduler (camctl) which handles image capture, timelapse compilation, and FTP upload to the server. This is separate from the server-side cron jobs above. See the camera system documentation for details.<\/p>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    4. Cache Files<\/h2>\n\n\n\n

                    All cache files live in the cache\/<\/code> directory at the web root. The directory must be writable by the web server user. Files are written atomically (tmp file then rename) to prevent partial reads.<\/p>\n\n\n\n

                    File<\/th>Written by<\/th>Read by<\/th>Notes<\/th><\/tr><\/thead>
                    sc_alerts.json<\/code><\/td>Tempest cron Step 5<\/td>includes\/alert-banner.php<\/td>Refreshed every 5 min. Stale after 10 min.<\/td><\/tr>
                    sc_wind_rose.json<\/code><\/td>Tempest cron Step 6<\/td>widget-wind-rose.php<\/td>Append-only, 30-day rolling window.<\/td><\/tr>
                    sc_moon_data.json<\/code><\/td>moon-cache-cron.php<\/td>ScooterCam_SunMoon_Display, ScooterCam_Moonset_Predictor<\/td>Refreshed daily at 1 AM.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    Tempest API response files are cached in data\/tempest\/<\/code> using MD5-keyed filenames, managed automatically by the ScooterCam_Tempest class. OpenWeatherMap responses for the moonset predictor are cached in sys_get_temp_dir()<\/code> for 30 minutes using the pattern sc_owm_{md5}.json<\/code>.<\/p>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    5. PHP Classes<\/h2>\n\n\n\n

                    5.1 ScooterCam_Tempest<\/h3>\n\n\n\n

                    File:<\/strong> includes\/tempest.php<\/code><\/p>\n\n\n\n

                    The main weather data class. Wraps all Tempest WeatherFlow API calls with file-based caching. Key methods:<\/p>\n\n\n\n

                    Method<\/th>Description<\/th><\/tr><\/thead>
                    get_current()<\/code><\/td>Returns latest station observation array. Cached per config[tempest][cache_current].<\/td><\/tr>
                    get_historical($hours)<\/code><\/td>Returns obs array for past N hours from device endpoint.<\/td><\/tr>
                    get_forecast_daily()<\/code><\/td>Returns 10-day daily forecast array.<\/td><\/tr>
                    get_forecast_hourly($hours)<\/code><\/td>Returns N-hour hourly forecast array.<\/td><\/tr>
                    get_alerts($cache_path)<\/code><\/td>Derives 5 alert types from current obs. Reads\/writes sc_alerts.json for onset tracking.<\/td><\/tr>
                    get_temperature_trend($hours)<\/code><\/td>Returns trend direction and change amount over past N hours.<\/td><\/tr>
                    degrees_to_cardinal($deg)<\/code><\/td>Converts wind degrees to 16-point compass label.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    Alert thresholds are defined as class constants and can be adjusted without touching logic:<\/p>\n\n\n\n

                    Constant<\/th>Default<\/th>Meaning<\/th><\/tr><\/thead>
                    HIGH_WIND_THRESHOLD_MPH<\/code><\/td>25<\/td>Gust speed that triggers a high wind alert<\/td><\/tr>
                    FREEZE_THRESHOLD_F<\/code><\/td>32<\/td>Temperature at or below which freeze alert fires<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    5.2 ScooterCam_Sunset_Predictor<\/h3>\n\n\n\n

                    File:<\/strong> includes\/class-sunset-predictor.php<\/code><\/p>\n\n\n\n

                    Scores tonight’s sunset quality 0\u2013100 using two OpenWeatherMap calls: one for the observer’s location and one for a horizon point ~20 miles west over the lake (42.5593, \u221286.6461). Scoring factors: cloud coverage (40%), visibility (25%), humidity (20%), wind speed (15%), weather type (15%), horizon contrast (20%). Weights are normalized in calculateScore()<\/code>.<\/p>\n\n\n\n

                    getCurrentScore()<\/code> returns an array with score<\/code> (int), grade<\/code> (letter), description<\/code> (string), and breakdown<\/code> (per-factor array). The is_sunset_score_window()<\/code> method on ScooterCam_SunMoon_Display<\/code> gates display, returning true only between noon and sunset.<\/p>\n\n\n\n

                    5.3 ScooterCam_Moonset_Predictor<\/h3>\n\n\n\n

                    File:<\/strong> includes\/class-moonset-predictor.php<\/code><\/p>\n\n\n\n

                    Determines whether today features a notable moonset over Lake Michigan (full moon \u226580% illumination, setting 5\u20139 AM, in the western sky azimuth 225\u2013315\u00b0). If notable, scores viewing conditions using OWM cloud\/visibility data.<\/p>\n\n\n\n

                    Moon phase data is read exclusively from cache\/sc_moon_data.json<\/code> written by the daily cron. No RapidAPI calls occur at page load. OWM weather calls are cached 30 minutes in the system temp directory.<\/p>\n\n\n\n

                    5.4 ScooterCam_SunMoon_Display<\/h3>\n\n\n\n

                    File:<\/strong> includes\/class-sunmoon-display.php<\/code><\/p>\n\n\n\n

                    Renders all sun and moon HTML components: sunset score card, moonset score card, moon phase calendar, sun arc SVG, moon arc SVG, and current moon phase details. All time formatting uses the configured timezone via the private format_timestamp()<\/code> helper to prevent UTC display bugs.<\/p>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    6. Display Widgets<\/h2>\n\n\n\n

                    Widgets are self-contained PHP includes in includes\/widgets\/<\/code>. Each locates its own data source and renders HTML. Drop into any page template with a single include line.<\/p>\n\n\n\n

                    Widget file<\/th>Usage<\/th>Data source<\/th><\/tr><\/thead>
                    widget-tempest-chart.php<\/code><\/td>Temperature + wind 24-hour chart<\/td>Tempest get_historical(24) \u2014 already cached<\/td><\/tr>
                    widget-pressure-trend.php<\/code><\/td>Pressure sparkline + trend badge<\/td>Tempest get_historical(6) \u2014 already cached<\/td><\/tr>
                    widget-wind-rose.php<\/code><\/td>SVG 16-point wind rose, 30 days<\/td>cache\/sc_wind_rose.json<\/td><\/tr>
                    widget-sunset-quality.php<\/code><\/td>Sunset score + conditions<\/td>ScooterCam_Sunset_Predictor + Tempest (pressure, wind direction)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    All widgets check for a $tempest<\/code> instance in scope before creating one, and check for $historical<\/code> if already loaded, to prevent redundant instantiation when multiple widgets appear on the same page. Widget CSS is scoped with a widget-specific prefix to prevent conflicts with the main stylesheet or WordPress.<\/p>\n\n\n\n

                    6.1 Alert Banner<\/h3>\n\n\n\n

                    File:<\/strong> includes\/alert-banner.php<\/code>
                    Usage:<\/strong> <?php include __DIR__ . '\/includes\/alert-banner.php'; ?><\/code><\/p>\n\n\n\n

                    Reads cache\/sc_alerts.json<\/code> and renders colored dismissible banners for active weather events. Stale cache protection: condition-based alerts are suppressed if the cache is older than 10 minutes. Lightning alerts bypass this check since they use their own epoch-based expiry.<\/p>\n\n\n\n

                    Dismissal is tracked in sessionStorage<\/code> keyed by event epoch\/onset, so a new event of the same type (a new lightning strike, for example) re-displays even if the previous one was dismissed.<\/p>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    7. Weather Alert System<\/h2>\n\n\n\n
                    Alert type<\/th>Trigger condition<\/th>Clears when<\/th>CSS class<\/th><\/tr><\/thead>
                    Lightning<\/strong><\/td>Strike detected within past 60 min<\/td>Automatically, 60 min after last strike epoch<\/td>.sc-alert--lightning<\/code><\/td><\/tr>
                    Rain<\/strong><\/td>precip_type = 1 or precip rate > 0<\/td>precip_type returns to 0<\/td>.sc-alert--rain<\/code><\/td><\/tr>
                    Hail<\/strong><\/td>precip_type = 2<\/td>precip_type returns to 0<\/td>.sc-alert--hail<\/code><\/td><\/tr>
                    High Wind<\/strong><\/td>wind_gust \u2265 25 mph<\/td>Gust drops below threshold<\/td>.sc-alert--high_wind<\/code><\/td><\/tr>
                    Freeze<\/strong><\/td>air_temp \u2264 32\u00b0F (0\u00b0C)<\/td>Temperature rises above threshold<\/td>.sc-alert--freeze<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                    All alert data is derived from the Tempest station observation endpoint \u2014 the same endpoint used for current conditions. No separate alert API exists. Onset timestamps are preserved across cron runs by reading the previous sc_alerts.json<\/code> before writing the new one, allowing the banner to show “started 23 minutes ago” accurately.<\/p>\n\n\n\n

                    To adjust thresholds, change the HIGH_WIND_THRESHOLD_MPH<\/code> and FREEZE_THRESHOLD_F<\/code> constants at the top of the ScooterCam_Tempest<\/code> class in includes\/tempest.php<\/code>.<\/p>\n\n\n\n

                    \u2191 Back to top<\/a><\/p>\n\n\n\n

                    \n\n\n\n

                    8. Wind Rose Data Accumulator<\/h2>\n\n\n\n

                    Step 6 of the Tempest cron appends one record to cache\/sc_wind_rose.json<\/code> every 5 minutes:<\/p>\n\n\n\n

                    { \"t\": epoch, \"spd\": mph, \"gst\": mph, \"dir\": degrees }<\/code><\/pre>\n\n\n\n
                    Records older than 30 days are pruned on each cron run. Calm entries (0\/0 speed) are skipped. After 30 days the file contains approximately 8,640 entries at roughly 300KB.<\/p>\n\n\n\n
                    The wind rose widget bins these into 16 compass sectors (22.5\u00b0 each) and four speed bands, then renders a pure SVG rose scaled so the busiest direction fills 88% of the maximum radius. No JavaScript is required.<\/p>\n\n\n\n
                    \u2191 Back to top<\/a><\/p>\n\n\n\n
                    \n\n\n\n
                    9. Moon & Sunset Scoring<\/h2>\n\n\n\n
                    9.1 Sunset Score Factors<\/h3>\n\n\n\n
                    Factor<\/th>Weight<\/th>Optimal condition<\/th><\/tr><\/thead>
                    Cloud coverage<\/td>40 pts<\/td>25\u201355% sky cover (partial clouds catch light best)<\/td><\/tr>
                    Visibility<\/td>25 pts<\/td>10+ km (clear air = vivid color)<\/td><\/tr>
                    Humidity<\/td>20 pts<\/td>Below 45% RH (dry air = saturated color)<\/td><\/tr>
                    Wind speed<\/td>15 pts<\/td>5\u201315 mph (light movement)<\/td><\/tr>
                    Weather type<\/td>15 pts<\/td>Partly cloudy<\/td><\/tr>
                    Horizon contrast<\/td>20 pts<\/td>Different conditions at observer vs. horizon point over lake<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                    9.2 Notable Moonset Criteria<\/h3>\n\n\n\n
                    A moonset is flagged as notable only when all three<\/strong> conditions are met simultaneously:<\/p>\n\n\n\n