HeavenlyPointer

KO | EN

gitlite — search

#markdown #large-language-models #vue #web #openai #mcp #awesome #security #sql #monitoring

HeavenlyPointer

(★ 9)

Turn your Stack-chan (M5Stack **CoreS3** + 2-axis servo base) into a live satellite tracker. It learns your WiFi, downloads orbital data, figures out where it is, and then physically **points its face at satellites** as they pass overhead — showing the satellite name and live telemetry on screen.

파일 탐색기

ZIP 다운로드

- extensions.json
- DEVICE.md
- Aircraft.cpp
- Aircraft.h
- Balloon.cpp
- Balloon.h
- CelestialIcon.cpp
- CelestialIcon.h
- Compass.cpp
- Compass.h
- config.h
- Ephem.cpp
- Ephem.h
- idf_component.yml
- main.cpp
- Net.cpp
- Net.h
- Provision.cpp
- Provision.h
- SatIcon.cpp
- SatIcon.h
- ServoHead.cpp
- ServoHead.h
- ServoSetup.cpp
- ServoSetup.h
- Settings.cpp
- Settings.h
- Sky.cpp
- Sky.h
- Starlink.cpp
- Starlink.h
- Status.h
- UI.cpp
- UI.h
- web_assets.h
- WebControl.cpp
- WebControl.h
- Wmm.cpp
- Wmm.h
- wmm_coeffs.h
.gitignore
LICENSE
partitions_16MB.csv
platformio.ini
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Turn your Stack-chan (M5Stack **CoreS3** + 2-axis servo base) into a live
satellite tracker. It learns your WiFi, downloads orbital data, figures out
where it is, and then physically **points its face at satellites** as they
pass overhead — showing the satellite name and live telemetry on screen.

---

## What it does

1. **WiFi onboarding** — first boot shows a QR code and the setup network name
   (**`HeavenlyPointer`**) on screen. Scan the QR (or join that network from your
   phone's WiFi list); a setup form opens that **lists the nearby networks it
   found** — pick yours (or choose *Other* for a hidden SSID) and enter the
   password. Prefer not to use a phone? Tap **Touch entry** and use the on-screen
   network picker + keyboard.
2. **Pulls down & stores data** — once online it:
   - syncs **UTC time** from NTP (and saves it to the CoreS3 RTC),
   - finds **where it is** via IP geolocation (or your manual override),
   - downloads a **TLE satellite catalog** from [Celestrak](https://celestrak.org)
     and caches it to flash (LittleFS), with the fetch timestamp.
3. **Desk calibration** — place Stack-chan flat, face pointing straight
   forward, and tap whether the face points **North / East / South / West**.
4. **Live tracking** — using **SGP4** orbital propagation it computes, every
   second, the azimuth/elevation of every catalogued satellite, picks the one
   highest above your horizon, and drives the **pan/tilt servos** so the face
   points at where that satellite is in the sky.
5. **On-screen telemetry** — the display shows the tracked satellite's name,
   azimuth, elevation, slant range, altitude, orbital velocity, sub-satellite
   ground point, visibility, a **type icon** (station / Starlink / nav / weather
   / telescope / rocket body / comsat, drawn from the name), plus a polar sky
   plot and the servo angles.
6. **Phone web control** — point a browser at the Stack-chan's IP (shown in the
   screen's corner) to watch live telemetry and change the satellite
   configuration from anywhere on your network.

Tracking is fully local once data is cached — it keeps pointing even if WiFi
drops. WiFi is only re-used to refresh the catalog (every 12 h) and re-sync time.

---

## Hardware

M5Stack **Stack-chan** — CoreS3 (ESP32-S3, 16 MB flash / 8 MB PSRAM), 2" LCD,
GC0308 0.3 MP camera, **serial-bus pan/tilt servos**, 12 RGB LEDs, capacitive
touch. Full chipset/spec breakdown: [docs/DEVICE.md](docs/DEVICE.md) · official
device docs: <https://docs.m5stack.com/en/StackChan>.

- **M5Stack CoreS3** (ESP32-S3) — the brain inside Stack-chan
- **Stack-chan 2-axis servo base** — pan (azimuth) + tilt (elevation) Feetech
  serial-bus servos, driven by [StackChan-BSP](https://github.com/m5stack/StackChan-BSP)
- USB-C cable for flashing/power

> **Power:** for continuous tracking, keep the CoreS3 on USB-C. The pan/tilt
> servos draw their biggest current when moving and when the tilt motor holds
> the head up against gravity; the 550 mAh internal battery sags under that load
> and can't sustain it for long. (The firmware releases servo torque whenever
> it's idle to minimise this, but tracking sessions still want wall power.)

---

## What's new in v1.2.0

- **Point at the whole sky, not just satellites** — a new **target picker** adds the
  **Sun, Moon, planets**, and a catalog of **bright stars + deep-sky objects** (galaxies,
  nebulae, clusters). Every position is computed **offline** from the time + your
  location — accurate to well under the head's own pointing error.
- **Target picker, two ways** — on the device, **tap the top-center** of the screen to
  cycle category (*Satellites · Sun · Moon · Planets · Stars/DSO · Favorites*) and the
  **top corners** to step within it; or use the **Target card** in the web UI (dropdowns
  show each object's current elevation + whether it's up). Switching category lands on
  the **highest object the head can actually point at**.
- **One-tap favorites** — **ISS, Tiangong, and Hubble** shortcuts (tracks them when
  they're up, counts down to the **next pass** when they're not), **editable from the
  web UI** so you can curate your own list.
- **Live aircraft (ADS-B)** — point the head at **planes flying overhead**, pulled from
  a free online feed ([airplanes.live](https://airplanes.live)). It locks onto the most
  overhead aircraft **the head can actually point at** — so it's aiming at a plane whenever
  one is in reach instead of sitting idle on one behind the head — and **stays with that
  same plane** across refreshes (browse the rest with prev/next), showing its **callsign,
  altitude, ground speed and distance**. It **dead-reckons** position *and* altitude
  between fetches so the head tracks smoothly and the readouts evolve as it climbs/descends.
  The **search radius is web-adjustable** — tighten it near a busy airport, widen it out in
  the country. Online-only (needs WiFi).
- **Starlink train** — track a freshly-launched **Starlink "train"**, the string of ~20–60
  satellites that fly in a tight line for days after a launch before raising orbit and
  spreading out (a spectacular naked-eye string of moving dots). It pulls Celestrak's
  **recent-launch** data and automatically identifies the **freshest cluster** — lowest
  orbit, so least spread and best viewing — by clustering the new Starlinks by orbital
  plane, then **SGP4-tracks** it: the head follows the most-overhead member as the line
  crosses the sky, and **counts down to the next train pass** when it's not up. Loads on
  demand (a one-time ~95 KB download), then runs offline from cache.
- **High-altitude balloons** — point the head at **weather radiosondes and amateur "pico"
  balloons** (which reach ~30 km) heard near you on the **APRS-IS** network. It keeps a
  persistent, range-filtered APRS-IS connection running in the background, parses the
  balloon position beacons (callsign, altitude, speed), and tracks the most-overhead one
  with the same sticky / prefer-reachable behaviour as the aircraft tracker. Balloons are
  sparse and beacon every few minutes, so the list fills in as it listens. Online-only.
- **Comets** — point the head at famous **comets** (1P/Halley, 12P/Pons-Brooks, 103P/Hartley,
  67P, Hale-Bopp, the three **interstellar visitors** 1I/ʻOumuamua, 2I/Borisov and 3I/ATLAS, and
  more), computed fully **offline** from their orbital elements by solving the comet's orbit each
  tick — **Kepler** for elliptical, **hyperbolic Kepler** for the interstellar (e>1) ones, **Barker**
  for parabolic — and projecting to topocentric az/el, the same pipeline as the planets, with
  **distance in AU**. The catalog is a built-in snapshot of MPC elements; periodic-comet positions
  stay valid for decades.
- **Sun page** — today's **sunrise / sunset / solar noon** + day length.
- **Moon page** — the **phase** name and **% illuminated** with a **phase-accurate Moon
  icon**, plus **moonrise / moonset**.
- **Celestial icons** — code-drawn icons for the rayed Sun, each planet type (rocky /
  gas-giant / ringed / ice-giant), 5-point stars, and galaxy / nebula / cluster.
- **Distances in miles** — bodies in miles (Moon, planets), stars in **light-years +
  miles**; the celestial HUD drops the satellite-only altitude / velocity / sub-point.

---

## What's new in v1.1.0

- **Magnetometer auto-heading** — let the on-board compass figure out which way
  "forward" is instead of tapping N/E/S/W, with **offline magnetic→true-north
  correction** (embedded World Magnetic Model 2025, NOAA-verified). Manual facing
  is always available as a fallback, and a poor/absent fix auto-reverts to it.
- **On-screen servo tools** — set a replacement servo's **bus ID** (pan 1 / tilt 2)
  and **re-zero "forward/level"** (Set center) right on the device — no external
  Feetech programmer needed.
- **Servo-protection guards** — defense-in-depth against the burnout: torque is
  released when idle/asleep, the motor-test holds auto-relax after 30 s, a **stall
  guard** cuts torque if the head is jammed, and a **low-battery guard** relaxes +
  warns below 20 % on battery.
- **Reach-aware countdown** — the next-pass timer now counts down **only to passes
  the head can actually point at**; if the soonest pass is outside the reach arc it
  says so (and to widen limits / check facing) instead of misleading you.
- **Smoother WiFi setup** — instant cached network list with a working Rescan,
  show/hide password, a **Back** button, the chosen network shown on the password
  screen, and clean recovery from a wrong password (no reboot needed).
- **Offline mode** — out of WiFi range but the data's already cached? The setup
  screen now offers an **Offline mode** button that tracks on the **cached TLEs +
  saved location + RTC clock**, no WiFi required. A failed connection also no
  longer wipes your saved WiFi, so it reconnects automatically once you're home.
- **4-tap standby** — **four quick taps** anywhere on the screen drops the device
  into standby (head goes limp, screen + LEDs off, WiFi stays up); **four more taps
  wake it**. Works alongside the web SLEEP/WAKE button and the sleep schedule.
- **Footer** — local **date** and **battery %** added to the on-screen footer.
- **Readouts** — range & altitude show in **miles**, **velocity in mph**, and
  velocity is now computed with the **vis-viva equation** (accounts for orbital
  eccentricity) instead of a circular-orbit estimate.

---

## Install (flash a prebuilt release)

Pick whichever is easiest — all three flash the same v1.2.0 image. That single
image already contains the bootloader, partition table and app; the device
formats its own filesystem and downloads satellite data on first boot, then drops
into WiFi setup (see [Using it](#using-it)).

### M5Burner (GUI, no toolchain)

HeavenlyPointer is published in the **M5Burner** firmware catalog:

1. Download and install **[M5Burner](https://docs.m5stack.com/en/uiflow/m5burner/intro)** (Windows / macOS / Linux).
2. Open it and, if prompted, sign in with a free M5Stack account (required to download catalog firmwares).
3. Find **HeavenlyPointer** — use the search box or the **STACKCHAN** device category.
4. Click **Download**, then **Burn**.
5. Connect the CoreS3 over USB-C, select its serial port, leave the baud rate at the default, and click **Burn**.
6. Wait for the success message — the device reboots into WiFi setup.

### Browser (no install)

[⚡ Flash from your browser](https://r3dfish.github.io/HeavenlyPointer/) with Chrome or
Edge: plug in the CoreS3 over USB-C, click **Connect**, pick its port, and flash.

### Command line (esptool)

Download `HeavenlyPointer-v1.2.0.bin` from the **[Releases](https://github.com/r3dfish/HeavenlyPointer/releases)** page, then:

```bash
# esptool (pip install esptool); add --port /dev/ttyACM0 (Linux/Mac) or COMx (Windows) if needed
esptool.py --chip esp32s3 --baud 1500000 write_flash 0x0 HeavenlyPointer-v1.2.0.bin
```

(You can also point M5Burner's **Custom firmware** at that `.bin` and burn it at offset `0x0`.)

---

## Build from source (PlatformIO)

Prereqs: [PlatformIO](https://platformio.org/) (the VS Code extension or the
`pio` CLI) and `git`.

```bash
git clone https://github.com/r3dfish/HeavenlyPointer.git
cd HeavenlyPointer
pio run                      # build (first run downloads the toolchain + libraries)
pio run -t upload            # flash the firmware
pio run -t uploadfs          # (optional) create the LittleFS data partition
pio device monitor           # serial log @ 115200
```

PlatformIO pulls the libraries automatically (see `platformio.ini`):
`M5Unified`, [`StackChan-BSP`](https://github.com/m5stack/StackChan-BSP)
(drives the servos/RGB/power), `ArduinoJson`, and the
[Hopperpop SGP4 library](https://github.com/Hopperpop/Sgp4-Library).

> The Stack-chan's pan/tilt servos are **Feetech serial-bus servos** driven by
> StackChan-BSP — *not* PWM hobby servos on GPIO pins. The BSP also requires
> **arduino-esp32 3.x**, which is why `platformio.ini` uses the **pioarduino**
> platform fork rather than stock `espressif32`.

---

## ⚠️ Calibration — do this first

Because the BSP owns the servos, there are no pins to wire — but the head
geometry in [`src/config.h`](src/config.h) should be checked on hardware. Use
the live `pan`/`tilt` readout on the tracking screen to dial these in:

| Constant | What to set |
|---|---|
| `YAW_DIR` | `+1`/`-1` — flip if the head pans the *wrong way* (e.g. turns toward West when the satellite is East). |
| `YAW_LIMIT_TENTHS` | Pan limit in 1/10°. `1200` = ±120° (near the ±1280 electronic limit). **Verify the head physically clears the mechanical stop at this angle** — driving into the stop stalls the pan servo and trips its overload protection (head goes limp until power-cycled, and a hard stall can strip the gears). |
| `PITCH_HORIZON_TENTHS` | Pitch value (1/10°) that aims the face at the **horizon** (elevation 0). The main thing to calibrate. |
| `PITCH_DIR` | `+1`/`-1` — flip if the head tilts *down* when the satellite rises. |
| `PITCH_MIN_TENTHS` / `PITCH_MAX_TENTHS` | Safe pitch band, default `50`–`850` (5°–85°). **Keep within 5°–85°** — the product page warns the Y-axis is damaged outside this range. |
| `SERVO_SPEED` | BSP smoothing speed `0`–`1000` (default `250`). |

> Angles are in **1/10-degree units** to match StackChan-BSP (e.g. `900` = 90°).
> The BSP runs its own smoothing engine, so there's no slew/tick tuning to do.

### Replacing a servo (bus IDs)

The Stack-chan's Feetech serial-bus servos are addressed by **ID**: the pan
servo must be **ID 1**, the tilt servo **ID 2**. The firmware does *not* assign
IDs, and a brand-new servo ships as **ID 1** — so a replacement (especially the
tilt servo) must be re-IDed or that axis won't respond (it shows **NO RESPONSE**
in the Motor test, the same symptom as a dead servo).

Built-in tool — no external Feetech programmer needed: web UI → **Actions →
Servo ID setup**, which reboots into an on-screen tool that scans the bus and
lets you set the connected servo to ID 1 or 2.

> **Important:** servos sharing an ID are indistinguishable on the bus, so when
> changing an ID, **connect only the one servo you're changing** (unplug the
> other), set it, then reconnect the other and verify both in **Motor test**.

**Re-centering ("zero").** Each axis stores a *zero* shaft position in NVS
(defaults: yaw 460, tilt 620 raw counts); commanding 0° drives the servo's
**absolute** sensor to that count, so "forward/level" is repeatable across
reboots with no homing. A replacement servo keeps the stored zero, but its
sensor offset (and how the head seats on the toothed output spline) can shift
where 0° actually points. With **both** servos connected, hand-aim the head to
forward + level and tap **Set center** in the Servo ID tool — it captures the
current positions as the new zero (saved to the same NVS the BSP reads at boot),
so you don't have to hand-edit `PITCH_HORIZON_TENTHS` / facing. Fine-trim with
those `config.h` constants afterward if needed.

---

## Using it

| Step | What you see / do |
|---|---|
| First boot | QR code + "WiFi Setup". Scan & enter creds, or tap **Touch entry**. |
| Out of WiFi range | If it can't reach a saved network but already has cached data (TLEs + location + a valid clock), the setup screen shows an **Offline mode** button — tap it to track on cached data with no WiFi. Your saved WiFi is kept, so it reconnects automatically back home. |
| After connect | "Syncing time", "Finding location", "Downloading satellite data". |
| Calibrate | Tap the compass direction the face points. (Asked once.) Or switch to **Auto** heading in the web UI to use the magnetometer instead — see Heading below. |
| Tracking | Satellite name + telemetry + sky plot. The head moves to follow it. Tap the **top-left/top-right corners** to browse prev/next visible satellite. |
| Standby | **Tap the screen 4 times quickly** (away from the browse corners) to drop into standby — head limp, screen + LEDs off, WiFi still up. **Four more quick taps** wake it. |
| "Scanning the sky" | Nothing is above the horizon yet — it homes the head, **releases the servo torque** (so the tilt motor isn't holding the head up against gravity), and counts down to the **next pass it can actually point at** (satellite + HH:MM:SS + peak elevation). If the soonest pass is **outside the reach arc**, it says "out of reach" (widen limits / check facing) rather than counting down to something it can't track. The head re-energizes when a reachable satellite rises. |
| Reset | Press-and-hold the bottom of the screen ~3 s to wipe config & re-provision. |

### Name-bar colour = optical visibility

The strip behind the satellite name (and the matching word lower on the screen)
tells you whether you could actually *see* the satellite right now:

| Colour | Meaning | Why |
|---|---|---|
| 🟢 **Green** | **visible** | Sunlit satellite **and** your sky is dark — you could spot it crossing overhead (e.g. an ISS flyover). Go look. |
| 🔵 **Blue** | **eclipsed** | Above your horizon and the sky is dark, but the satellite is in **Earth's shadow** — not catching sunlight, so there's nothing to see. |
| 🔴 **Dark red** | **daylight** | The sun is up where you are — still tracked, just too bright to see. |

A blue → green change is the satellite emerging from Earth's shadow into
sunlight while your sky is dark — the moment it would "light up" to the eye.

---

## Web control (phone / browser)

Once on WiFi, the Stack-chan runs a small web server. Open **`http://<its-ip>/`**
in any browser on the same network — the IP is shown in the corner of the
screen. The page shows **live telemetry** (auto-refreshing), has **◀ Prev / Next ▶**
buttons to browse the currently-visible satellites (same as the on-screen corner
taps), and lets you change the **satellite configuration** without touching the
device:

| Setting | Effect |
|---|---|
| **Catalog group** | Switch between `visual` / `stations` / `amateur` (ham-radio sats) / `active` / `weather` / `starlink` / `gps-ops`. Triggers a re-download. |
| **Name filter** | Track only satellites whose name contains this text (e.g. `ISS`, `NOAA`, `STARLINK`). Blank = everything. |
| **Reach limits** | Min/max elevation and azimuth (pan ±°) the head can point at. The tracker **only selects satellites inside these limits** — and if the one it's following drifts out of range, it **automatically switches to the next in-range satellite** (or parks if none is reachable). |
| **Orbit class** | `LEO only` (default — fast passes that sweep the sky), `Skip geostationary` (LEO + MEO), or `All orbits`. Classified by mean motion: LEO ≥ 11.25, MEO ~2, GEO ~1 rev/day. |
| **Heading** | How the head finds "forward" (true north). **Manual** = pick N/E/S/W or type an exact bearing. **Auto** = read it from the on-board magnetometer. Auto needs a one-time **Calibrate compass** (rotate the device through a full turn); a **Mounting trim** nudges the reading if it's consistently off. The page shows a live heading/quality readout, and if a magnetometer fix is poor (tilted base, magnetic clutter) it **falls back to your manual setting** automatically. |
| **Declination** | Magnetic → true-north correction for the magnetometer. **Auto** computes it on-device from your location with the embedded **World Magnetic Model 2025** (no network); untick to enter your local declination by hand. |
| **Observer location** | Shows the **geolocation status** (📍 city + coordinates on success, or a ⚠ failure notice). Override lat/lon, or tap **Auto-locate from IP**. |
| **Clock offset** | UTC offset (hours) for the displayed clock — auto-detected from your IP, override here. Tracking itself always uses UTC. |
| **LED bars** | RGB bars **green while tracking**, **red while waiting** for the next pass. On by default; uncheck to turn them off. |
| **Sleep schedule** | Quiet hours — set a local **Sleep at / Wake at** window. During it the head goes limp (servo torque released), and the screen + LEDs turn off (WiFi stays up). Toggle to enable. |
| **Actions** | Re-download TLEs, recenter the head, **Recover servos** (re-enable torque after a stall), **Servo ID setup** (reboots into the on-screen bus-servo ID tool — see below), or **SLEEP NOW** (the button becomes **WAKE NOW** while asleep). |
| **Motor test** | Tick **Test mode** to pause tracking and drive the pan/tilt servos directly (sliders, presets, and **Sweep pan / Sweep tilt**). Bypasses all az/el math, so it isolates each physical motor — if "Sweep pan" moves nothing but "Sweep tilt" works, the azimuth servo isn't responding. |

While asleep the device keeps serving the web page, so you can **WAKE NOW** from
your phone — or **tap the (dark) screen 4 times quickly** to wake it. A manual wake during a
scheduled window holds until the next window edge, when the schedule resumes.

Changes persist to NVS and apply immediately (a group change kicks off a
catalog re-download, during which the head holds its last position).

The JSON API behind the page (handy for scripting):

| Endpoint | Method | Purpose |
|---|---|---|
| `/` | GET | The control page |
| `/status.json` | GET | Live target + telemetry + servo angles + IP + time |
| `/config.json` | GET | Current saved configuration |
| `/config` | POST | Apply config (form fields: `group`, `filter`, `minel`, `maxel`, `panlim`, `orbit`, `facing`, `hsrc`, `mhead`, `hoff`, `declauto`, `decl`, `lat`, `lon`, `tzoff`, `leds`, `sleepsched`, `sleepstart`, `sleepend`) |
| `/action` | POST | `cmd=` `refetch` \| `relocate` \| `park` \| `prev` \| `next` \| `sleep` \| `wake` \| `recover` \| `calmag` \| `applyhead` \| `servosetup` \| `test` \| `testexit` |
| `/test` | POST | Motor test: `pan` / `tilt` in degrees (only while test mode is active) |

> No authentication — intended for your **local network** only. Don't port-forward it.

The default catalog group on a fresh install is still `DEFAULT_TLE_GROUP` in
[`src/config.h`](src/config.h); the web UI overrides it at runtime thereafter.

---

## Project layout

```
platformio.ini        Build config, board, libraries, partition table
partitions_16MB.csv   16 MB flash map with a LittleFS data area for TLEs
src/
  config.h            All tunables + servo/mount calibration (edit this!)
  Settings.*          Persistent config in NVS (WiFi, location, facing, catalog)
  Net.*               WiFi connect, NTP, IP geolocation, TLE download+store
  Provision.*         Captive-portal + on-screen QR + touch-keyboard onboarding
  Sky.*               Loads TLEs, runs SGP4, picks the best reachable target
  ServoHead.*         az/el -> StackChan-BSP head pointing (1/10-degree units)
  ServoSetup.*        On-screen Feetech bus-servo ID tool (after a servo swap)
  Compass.*           Tilt-compensated magnetometer heading + mag calibration
  Wmm.*               Offline World Magnetic Model 2025 (magnetic declination)
  wmm_coeffs.h        Embedded WMM2025 spherical-harmonic coefficients (NOAA)
  UI.*                Screens: provision, keyboard, calibrate, tracking HUD
  SatIcon.*           Vector satellite icons by type (classified from the name)
  WebControl.*        HTTP server: live telemetry + satellite config API
  web_assets.h        Embedded phone control page (HTML/CSS/JS, PROGMEM)
  Status.h            Shared live-status struct + web-UI request flags
  main.cpp            State machine wiring it all together
```

---

## How the pointing works

```
SGP4(TLE, UTC time, observer lat/lon/alt)  ->  azimuth, elevation
relAz = wrap180(azimuth - forwardBearing)              # forwardBearing from N/E/S/W choice
yaw   = YAW_DIR   * relAz*10           (tenths, clamped to +/-YAW_LIMIT_TENTHS)
pitch = PITCH_HORIZON_TENTHS + PITCH_DIR * elevation*10 (tenths, clamped 5-85 deg)
M5StackChan.Motion.move(yaw, pitch, SERVO_SPEED)
```

The face can only *orient* (it can't translate), and a satellite is effectively
at infinity, so aiming the display normal along the (az, el) vector is exactly
"pointing at it."

---

## Troubleshooting

*(Device-level notes — these apply to the Stack-chan hardware in general.)*

- **`/dev/ttyACM0` busy / permission denied when flashing** — on Linux your user
  needs the `dialout` group active. One-off: `sudo chmod a+rw /dev/ttyACM0`;
  permanent: add yourself to `dialout` and log out/in.
- **Build fails on the StackChan-BSP / `std::make_unique` / ESP-IDF 5 APIs** —
  the BSP needs **arduino-esp32 3.x**, which is why `platformio.ini` uses the
  **pioarduino** platform fork (not stock `espressif32`) and fetches the BSP
  from git, so PlatformIO needs `git` available.
- **Head pans or tilts the wrong way** — flip `YAW_DIR` / `PITCH_DIR` in
  [`src/config.h`](src/config.h) (see [Calibration](#️-calibration--do-this-first)).
- **An axis reads "NO RESPONSE" / doesn't move (often after a servo swap)** — the
  replacement servo's **bus ID** is wrong. Set it with **Actions → Servo ID setup**
  (pan = 1, tilt = 2) — see [Replacing a servo](#replacing-a-servo-bus-ids).
- **Always "no upcoming passes" / "out of reach", never a countdown** — the tracker
  only counts down to passes it can *point at*. Widen the **pan ±°** and **min/max
  elevation** reach limits and confirm the **facing/heading**; passes that fall
  inside the arc will then count down and get tracked.
- **Camera shares the CoreS3 internal I²C bus with the touch panel.** This
  firmware uses touch (not the camera), so it's fine — but if you later add the
  GC0308 camera (e.g. for auto-heading or QR scanning), it contends with the
  touch controller on that bus and they can't both be live at once.

---

## Notes & limitations

- **Azimuth coverage** is limited by the pan servo's travel (±120° by default).
  The head clamps and the HUD shows **OUT OF RANGE** when a
  target is further around than the head can turn — rotate the whole robot or
  change the facing direction to recenter the workable arc.
- **Elevation coverage** is limited to the safe 5°–85° pitch band, so satellites
  very near the horizon or directly overhead clamp at the nearest limit.
- **Accuracy** is as good as your TLEs (refreshed every 12 h), your clock (NTP),
  your location (IP geolocation is city-level — set lat/lon in the setup form
  for precision), and your physical leveling/centering.
- **Geolocation/data** use public endpoints (`ip-api.com`, `celestrak.org`).
  TLS certs are not pinned (`setInsecure`) to keep it light on the MCU.
- The servos are **Feetech serial-bus servos** driven by StackChan-BSP; the head
  geometry constants are sensible defaults but should be confirmed on hardware.

HeavenlyPointer

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

HeavenlyPointer

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README