mctl README

项目的 README,来自 github.com/LiamDroog/mctl。合并为一个 markdown 文件:README.md。

mctl

mctl is a spacecraft display written in Rust. It follows the ISS, the Crew and Cargo Dragons that visit it, Hubble, JWST, Roman, the Tiangong station, and Voyager 1 and 2 and New Horizons, and tries to look like a retro flight control room monitor: a 3D orbit map, ground track, sky plot, pass predictions, a maneuver planner, and live telemetry from the ISS. I wanted something to leave running on a screen at home.

It's got seven themes (green phosphor, amber, retrowave, a plain dark one, and Soviet red, Teletext and Nostromo teal). It also has a low-resolution mode for a Raspberry Pi feeding a Commodore 1702 CRT over composite, which is how I run mine, r/casettefuturism unite!

The MASTER page in the Phosphor theme

The themes, on the same page (T cycles them):

Phosphor Retro
Retrowave Modern
Cosmonaut Teletext
Nostromo

Full disclaimer, most of the code was written with Claude, Rust is not my expertise but my implementation with Python ran, well, it was seconds per frame rather than frames per second.

Currently mctl has only been really tested in kubuntu and on a Pi 3B+. It runs in Ubuntu under WSL2 on Mesa's software renderer, slowly, and uses X11 there because WSLg's Wayland drops the connection when you resize. YMMV.

What that display do?

The function keys switch pages and Tab steps through the sub-pages of each one.

Installing

A release

Each release has a tarball for x86-64 and one for aarch64 (a Raspberry Pi 3 or later running a 64-bit OS), plus checksums. They are built against glibc 2.35, so they need Ubuntu 22.04, Debian 12 or newer. Unpack one and run ./mctl. If it complains about a missing library, packaging/bootstrap.sh in the tarball works out what's missing and installs it, and packaging/install.sh puts the binary and a desktop entry in ~/.local. One can also just run packaging/bootstrap.sh to install from source, details below.

From source

On a fresh machine:

git clone https://github.com/LiamDroog/mctl
cd mctl
packaging/bootstrap.sh

It checks for a C compiler, curl, the libraries the window needs, a Vulkan driver, and Rust 1.95 or newer. It tells you what's missing, asks, and installs it: system packages through apt, dnf or pacman, and Rust through the official rustup installer into ~/.cargo if there's no recent enough one. Then it builds mctl and installs it into ~/.local. The first build takes a few minutes on a desktop. Don't do it on a Pi 3; use a release. Unless you've got lots of time, then you do you. I won't tell you how to use your time.

It has a few switches:

packaging/bootstrap.sh --check              # just report what's missing, change nothing
packaging/bootstrap.sh --dry-run            # show what it would do
packaging/bootstrap.sh --yes                # don't ask
packaging/bootstrap.sh --no-system-packages # never touch apt/dnf/pacman, only tell me
packaging/bootstrap.sh --prefix /usr/local  # install somewhere else

The package names are set for apt (Debian, Ubuntu, Raspberry Pi OS), dnf (Fedora) and pacman (Arch). So far only apt has been tried on a real machine. If you'd rather do it by hand, you need build-essential or the equivalent, then cargo build --release --locked -p mctl.

packaging/install.sh --uninstall removes it again. If you're working on the code, scripts/mctl-launch is a launcher that rebuilds before it runs; symlink it as mctl somewhere on your PATH.

Using it

mctl                            # the console
mctl --vehicle jwst --theme retrowave --fullscreen    # iss, hubble, jwst or roman
mctl --offline                  # use cached data only; nothing is fetched, pictures come from the cache
mctl check                      # check the config and fetch each data source once
mctl about                      # licence, credits, third-party notices
mctl --replay start             # play back your recording (or an ISO time, or an offset like -2h)
mctl --no-record                # don't record this run
mctl export --out ./dump        # every recorded table as CSV
mctl shot --out-dir /tmp/shots --pages all    # headless screenshots, one per theme and page

Currently the kiosk/unattended mode only work with the --kiosk flag, with simplified layouts and a cycle through the screens. In progress for a regular kiosk mode.

The keys, all of which can be remapped under [keys] in the config:

Anything that isn't a plain measurement carries a short flag: [EST] for estimated, assumed or configured, [PLAN] for scheduled rather than happening, [TLE] for derived from a TLE and not trustworthy inside about 5 km, [SURVEY] for a sky-survey picture, and [NOW] for a current value shown while the clock is somewhere else. ? has the legend.

On a Raspberry Pi and a CRT

Pi mode cycling through a few scenes

mctl --kiosk is a second front end on the same engine, built to be looked at rather than driven. It cycles through the vehicles, with line art, maps, and the console's own pages, and it draws without the CRT effects because the tube does those itself. It scales to fill whatever screen it is on: the layout is designed for the Pi's 640x480 and a larger screen gets the same layout in bigger text. (--pi still works as an alias.) --size runs it in a window of that size instead.

mctl --kiosk                                       # fullscreen, cycling
mctl --kiosk --kiosk-style dense --theme retrowave    # console pages only, in retrowave
mctl --kiosk --kiosk-order random                  # every scene once per cycle, a new random order each cycle
mctl --kiosk --kiosk-order vehicle --kiosk-vehicles iss,jwst   # one vehicle at a time, in random order
mctl --kiosk --kiosk-order random --kiosk-theme-cycle   # a different random theme with every scene
mctl --kiosk --max-fps 5                           # draw fewer frames to use less CPU (or [display] max_fps)
mctl --kiosk shot --out-dir /tmp/pi                # one PNG per scene

The pictures look good on a CRT. The dense console pages are hard to read at that resolution. A Pi 3B+ has no Vulkan GPU, so it renders in software and the frame rate is modest. The setup, the composite output and cross-building for a Pi are in docs/pi.md.

Live data? Propagated data? Fake data?

mctl pulls live data where available. These contain:

mctl identifies itself in its requests, revalidates with ETags and backs off when something fails. The licences for the images and fonts it embeds are in assets/LICENSES.md.

Unfortunately required disclaimers

This is a hobby display. Don't use it for operations, navigation, or anything where being wrong matters. It isn't affiliated with or endorsed by NASA, ESA, STScI, SpaceX or anyone else whose vehicles or data it shows. If you happen to be in a situation where you're piloting a spacecraft and this is your only means of navigation, please, and I say this lovingly, please reevaluate the chain of decisions that have gotten you into this pickle.

Some specifics about what you're looking at:

Configuration and files

The defaults are built in (config/default.toml). A file at ~/.config/mctl/config.toml overrides any key, and a bad value stops the program with an error rather than being ignored. Downloaded data is cached in ~/.cache/mctl, logs go to ~/.local/state/mctl/mctl.log, and your recording is ~/.local/share/mctl/mctl.db, a SQLite file kept for 30 days or 2 GB. Only real time is recorded, never simulated states.

For passes, the observer site is the one you configure, otherwise GeoClue if your system allows it, otherwise a built-in NASA HQ fallback. There's also an IP lookup, which is off unless you switch it on and is the only thing that would send anything about you anywhere. There's no telemetry or analytics. I don't really give a damn about who's using this. Unless you do happen to be in a situation where you're piloting a spacecraft with this software. Please let me know about that. If you survive.

Contributing

Bug reports and pull requests are welcome; CONTRIBUTING.md has the details. For security problems, see SECURITY.md. docs/architecture.md is a tour of how the code fits together, and the crates are:

Credits and licence

I credit the copious amout of synthwave and retrowave music and the desire for a retrofuturistic (Hi, r/casettefuturism!) display piece in my home. The idea, the design, the testing and the Pi and CRT setup are mine; Claude wrote much of the code and the documentation from that as was previously mentioned. Thanks to the people who keep CelesTrak, Horizons, the IERS, STScI and NASA's public data services running. mctl about prints the full credits, and the third-party notices are in THIRD-PARTY-NOTICES.md. Anyone crazy kind enough to contribute to the repo will also be acknowledged here.

mctl is free software under the GNU General Public License, version 3 or (at your option) any later version. See LICENSE. Please don't sell this. If you want to use it in any published media (short/long form) please contact me before use.

mctl (LiamDroog/mctl)

正在搜索数据库…

165 ·GitHub
这是什么?mctl 是一个用 Rust 编写的桌面显示程序,用于追踪国际空间站(ISS)、Dragon 飞船、哈勃、JWST、Roman、天宫、旅行者 1 号和 2 号以及新视野号。它以任务控制中心风格的仪表盘呈现,包括 3D 轨道图、地面轨迹、天空图、过境预测、机动规划器和实时国际空间站遥测数据。
这是命令行工具还是图形界面应用?这是一个全屏图形桌面应用,而不是命令行工具。你需要像操作飞控台一样使用功能键来操作它,并且需要支持 Vulkan 的 GPU 才能渲染带主题的 CRT 风格屏幕。
我怎么让它跑起来?下载 x86-64 或 aarch64 架构的发布压缩包,解压后运行 ./mctl。也可以运行 packaging/bootstrap.sh 从源码构建,该脚本会检查依赖项、安装缺失的组件,并使用 cargo 构建项目。
稳定性方面我该有什么预期?作者实际只在 Kubuntu 和树莓派 3B+ 上测试过。在 WSL2 下使用软件渲染器运行速度较慢。OPS 页面显示的是巡天图像截图,而不是哈勃或 JWST 的真实图像。ISSLIVE 等数据源是非官方的,可能随时变化或消失。
它能在 Windows 或 Mac 上运行,还是只支持 Linux?仅支持 Linux。发布版针对 x86-64 和 aarch64(树莓派 3 及以上)构建,基于 glibc 2.35,需要 Ubuntu 22.04、Debian 12 或更新版本。它可以在 WSL2 的 Ubuntu 下借助软件渲染器勉强运行,但不原生支持 macOS 或 Windows。
mctl 会把我的数据发送到什么地方吗?默认不会。唯一可能发送任何相关信息的功能是可选的 IP 查询,除非你手动开启,否则默认关闭。除此之外,没有任何遥测或分析功能。
树莓派模式有什么特别之处?专用的 --kiosk 前端会跳过 CRT 着色器效果(因为真实的显像管本身就能呈现这种效果),可适配任意屏幕尺寸,并旨在为复合视频 CRT 显示器(如 Commodore 1702)提供信号,以打造复古任务控制中心的视觉效果。
实时数据从哪里来?轨道根数来自 CelesTrak,国际空间站遥测数据来自公开的 ISSLIVE Lightstreamer 数据流,深空轨迹(JWST、Roman、旅行者号、新视野号)来自 JPL Horizons。天空图像来自 Digitized Sky Survey(数字化天空巡天),经由 CDS 斯特拉斯堡或 STScI/MAST 获取。
机动规划器有多准确?它对轨道进行数值积分,考虑了 J2-J4 项、太阳和月球引力以及大气阻力。在未使用阻力模型时,积分一天后与 NASA 的国际空间站星历表相差 3.1 公里;使用简单阻力模型时相差 7.3 公里。这作为业余显示足够用了,但不能用于实际导航。
复古 CRT 主题是什么样的?共有七种可切换的主题:绿色荧光、琥珀色、retrowave、普通深色主题、苏联红、Teletext 以及 Nostromo 青色,按 T 键依次切换。
作者
LiamDroog
大小
5.6 MB
星标
165
时长
19天
提交 · 90 天