Name: ZsBus Bus Arrival Notification
Author: cwlin0416

ZsBus is a real-time bus information app designed for Garmin smartwatches, helping you stay informed about bus arrival times for easier commuting in Taiwan!

Key Features
- Real-time Bus Information: Display estimated bus arrival times (minutes/seconds)
- Route Destination: Shows "To ..." so you can confirm the direction
- Next Bus: Press START to see the next departure and estimated arrival
- Work/Home Mode: Pre-set favorite routes for one-tap queries
- Nearby Stop Search: GPS-based search for nearby bus stops
- Arrival Alerts: Vibration notifications when bus is about to arrive
- English & Chinese: UI and stop names follow the watch language
- Taiwan-wide Support: Covers bus systems across all cities and counties in Taiwan

Quick Setup Guide

By default, ZsBus queries bus data through a proxy server, so no API key is required — just install and set your favorite stops.

Step 1: Set Up Regular Routes
Find ZsBus in the Garmin Connect app, enter the app settings page, and fill in your regular commuting stops:
- Work Stop UID: UID of the bus stop for work commute (e.g., NWT70716)
- Work Route UID: UID of the bus route for work commute (e.g., NWT17524)
- Home Stop UID: UID of the bus stop for home commute (e.g., NWT1000784)
- Home Route UID: UID of the bus route for home commute (e.g., NWT17524)

Don't know the stop/route UID? Use the "Nearby Stops" function to search and select by GPS first.

Advanced: Use Your Own TDX Key (Optional)
If you prefer to connect to TDX directly instead of through the proxy, you can use your own key:
1. Visit TDX Transport Data eXchange Platform (https://tdx.transportdata.tw/) to register and apply for an API key (Client ID and Client Secret)
2. On the app settings page:
   - Turn off "Use Proxy Mode"
   - Enter Client ID and Client Secret

When entering keys, avoid extra spaces or missing hyphens, otherwise "Connection Failed (Error Code: 400)" will appear.

How to Use

Main Screen Operations
1. Launch the ZsBus app
2. Use up/down buttons to switch between different function pages:
   - Group Page: Display preset work/home bus information
   - Nearby Stops: Search for nearby bus stops
   - Nearby Routes: Search for nearby bus routes

View Real-time Bus Information
- Route Name: Display bus route number
- To ...: The destination of this direction, to confirm you board the right way
- Stop Name: Display boarding stop
- Arrival Time:
  - X min Y sec: estimated countdown
  - "Arriving soon": within 3 minutes
  - "Arriving": countdown finished, about to pull in
  - "Not departed" / "Last bus gone" / "No service today" / "Not stopping": shown per the stop's live status
  - "Faster/Slower than est. Ns": cumulative drift vs the arrival predicted when you opened the view, shown when over 10s
  - "Stale data": the estimate hasn't progressed for over 90s (poor signal); treat the countdown as a rough guide

Next Bus (press START)
On the bus info screen, press START to switch to the "Next bus" panel:
- Next departure: exact time on timetable days; headway (every X min) on frequency days; first bus / tomorrow's first when outside service hours
- Estimated arrival: when a live bus exists, shows "~N min"
Press START again to switch back to the live ETA.

Nearby Stops/Routes Search
1. Select "Nearby Stops" or "Nearby Routes" function
2. The app will automatically get your GPS location
3. Display list of stops or routes within 100 meters
4. Select the desired stop or route for inquiry

Arrival Alert Function
- When bus is estimated to arrive within 3 minutes, the watch will automatically vibrate
- Helps avoid missing bus schedules

Important Notes

Network Requirements
- Watch needs internet connection (via phone or Wi-Fi)
- Recommended to use in areas with good signal

GPS Positioning
- GPS must be enabled for nearby stop search function
- Initial positioning may take longer

Data Updates
- Bus information updates automatically; refreshes faster as the bus gets close (within 3 min)
- 

ZsBus Bus Arrival Notification

ZsBus 是專為 Garmin 智慧手錶設計的台灣公車即時查詢應用程式，讓您隨時掌握公車到站時間，通勤更輕鬆！

主要功能
- 即時公車資訊：顯示公車預估到站時間（分鐘/秒）
- 路線終點：顯示「往○○」，確認搭乘方向是否正確
- 下一班次：按 START 查看下一班發車與預計到站
- 上班/回家模式：預設常用路線，一鍵查詢
- 附近站牌搜尋：基於 GPS 定位找尋附近公車站
- 到站提醒：公車即將到站時震動提醒
- 中英雙語：依手錶語言自動切換介面與站名
- 全台支援：涵蓋全台灣各縣市公車系統

快速設定指南

本 App 預設透過代理伺服器（Proxy）查詢公車資料，免申請金鑰、安裝後即可使用，您只需設定常用站牌即可。

步驟 1：設定常用路線
在 Garmin Connect 應用程式中找到 ZsBus，進入應用程式設定頁面，填入常用通勤站牌：
- 上班站牌 UID：上班搭車站牌的 UID（如：NWT70716）
- 上班路線 UID：上班搭乘路線的 UID（如：NWT17524）
- 回家站牌 UID：回家搭車站牌的 UID（如：NWT1000784）
- 回家路線 UID：回家搭乘路線的 UID（如：NWT17524）

不知道站牌/路線 UID？可先用「附近站牌」功能以 GPS 搜尋並選取。

進階：使用自己的 TDX 金鑰（選用）
若您希望直接連線 TDX、不透過代理伺服器，可改用自己的金鑰：
1. 前往 TDX 運輸資料流通服務平台 (https://tdx.transportdata.tw/) 註冊並申請 API 金鑰，取得 Client ID 與 Client Secret
2. 在應用程式設定頁面：
   - 關閉「使用 Proxy 模式」
   - 填入 Client ID 與 Client Secret

填寫金鑰時請避免多餘空白或缺漏連字號，否則會出現「連線失敗 (錯誤碼: 400)」。

使用方式

主畫面操作
1. 啟動 ZsBus 應用程式
2. 使用上下按鍵切換不同功能頁面：
   - 群組頁面：顯示預設的上班/回家公車資訊
   - 附近站牌：搜尋附近的公車站
   - 附近路線：搜尋附近的公車路線

查看即時公車資訊
- 路線名稱：顯示公車路線號碼
- 往○○：顯示該方向的終點站，確認搭乘方向
- 站牌名稱：顯示搭車站牌
- 到站時間：
  - X 分 Y 秒：預估到站倒數
  - 「將到站」：3 分鐘內即將到站
  - 「進站中」：倒數完畢、即將進站
  - 「尚未發車」/「末班已過」/「今日未營運」/「不停靠」：依該站別即時狀態顯示
  - 「比預估快/慢 N 秒」：以打開時的預估為基準，累積偏快或偏慢超過 10 秒時於最下方提示
  - 「資料停滯」：估計超過 90 秒沒前進（訊號不佳）時提示，倒數僅供參考

下一班次（按 START）
在公車資訊畫面按 START 切換至「下一班發車」：
- 下一班發車：假日顯示精確時刻；平日顯示班距（約每 X 分）；未營運時顯示頭班 / 明日頭班
- 預計到本站：有即時班次時估算「約 N 分後到」
再按一次 START 切回即時到站。

附近站牌/路線搜尋
1. 選擇「附近站牌」或「附近路線」功能
2. 應用程式會自動取得您的 GPS 位置
3. 顯示 100 公尺範圍內的站牌或路線清單
4. 選擇所需的站牌或路線進行查詢

到站提醒功能
- 當公車預估 3 分鐘內到站時，手錶會自動震動提醒
- 避免錯過公車班次

重要注意事項

網路需求
- 需要手錶連接網路（透過手機或 Wi-Fi）
- 建議在訊號良好的環境下使用

GPS 定位
- 使用附近站牌搜尋功能需要開啟 GPS
- 首次定位可能需要較長時間

資料更新
- 公車資訊自動更新；接近到站時（3 分內）會加快更新以更準確
- 手動重新進入頁面可立即更新

語言
- 介面文字與站名會依手錶系統語言自動切換中文 / 英文

電池使用
- 持續使用 GPS 和網路會消耗較多電量
- 建議在需要時才開啟應用程式

故障排除

常見問題

Q: 顯示「更新錯誤」或「連線失敗」怎麼辦？
A: 請檢查：
- 網路連線是否正常（手錶需透過手機或 Wi-Fi 連線）
- 站牌/路線 UID 是否正確設定
- 若使用直連模式（已關閉 Proxy）：
  - 「連線失敗 (錯誤碼: 400)」通常是 Client ID 有誤（多餘空白或缺連字號）
  - 「API 金鑰錯誤 (401)」通常是 Client Secret 有誤
  - 是否超過 API 使用額度

Q: 找不到附近站牌？
A: 請確認：
- GPS 定位是否成功
- 是否在台灣境內
- 附近 100 公尺內是否有公車站

Q: 公車時間不準確？
A: 公車到站時間為預估值，實際情況可能因交通狀況而有差異

ZsBus 使用 TDX 運輸資料流通服務提供的開放資料，感謝交通部運輸資料流通服務平台的支持。