Heimdall

An open-source lower-screen game assistant built for AYN Thor.

Download Alpha · Setup Guide · 简体中文设置指南 · Report an issue

English | 简体中文

Heimdall keeps the game on Thor's upper screen while the lower screen becomes a persistent control and reference console: Profiles, macros, touch controls, translation, hardware status, maps, guides, local-media Canvases, magnification, recording, and Quick Actions stay within thumb reach.

Alpha software: Heimdall targets AYN Thor. Compatibility is not guaranteed for every Thor firmware, controller mode, game, emulator, or other dual-screen device.

Heimdall On A Real AYN Thor

Active play: Precision Aim and circular magnification	Profile controls: magnifier, touchpad, and Macros
Reference: a local Guide without covering the game	Execution: Canvas move list and structured Macros

What You Can Do

Play view: controls stay glanceable on the lower screen	Edit view: drag modules and resize from visible corners

Start Here: Choose Only What You Need

Installing Heimdall does not require root or Developer options. Developer options are needed only if you want to start Shizuku for advanced controller features.

You do not need to enable every permission during first launch. Start with one Profile and one route, test it, then add features as needed.

1. Download And Install

1. Open the Heimdall Releases page.
2. Open the newest versioned Alpha release.
3. Download the file named like heimdall-vX.Y.Z-alpha.N.apk. The same release also includes SHA256SUMS.txt for file verification.
4. Open the APK with Thor's file manager.
5. If Android asks, allow that file manager to install unknown apps, return to the installer, and finish installation.
6. Open Heimdall.

Install only immutable, versioned releases from this repository. The mutable private-development debug-latest channel is not a public release, and re-signed APKs from unknown sources should not be trusted.

Updating Or Moving From An Older Test Build

Official Alpha updates signed with the same release identity can normally install over the previous public Alpha. Do not uninstall first unless the release notes explicitly require it: uninstalling removes local Profile data and imported assets.

Older test packages and new Debug builds may be separate Apps and do not share data with the public package com.mastercook777.heimdall.

Before moving from an older test build:

1. Open Profile management in the old build.
2. Export all Profiles and keep the exported file somewhere easy to find.
3. Install and open the public Alpha.
4. Re-authorize the services you use.
5. Import the exported file and confirm the important Profiles before deleting the old build or backup.

Older builds export configuration-only JSON, which remains importable but cannot recover missing external assets. Current builds export a self-contained .heimdall-profile bundle containing Profile data plus supported Profile icons, maps, file Guides, user Macro icons, and Canvas media.

2. Create Your First Profile

1. Open Settings > Profile management.
2. Create a Profile for one game or emulator.
3. Start the target App on the upper screen, then bind it from Heimdall's recent-App selector.
4. Choose a Grid preset. Balanced is the easiest starting point; Controls reserves more room for touch controls, and Macros shows more actions.
5. Add only the modules you want now.
6. Tap Save at the bottom of Settings.
7. Switch back to the game and confirm Heimdall selects the expected Profile.

Save boundary: Grid and several Profile settings use preview/draft state. Seeing the preview does not mean it has been stored; save before leaving the editor or Settings.

3. Enable Basic Touch (Optional)

Basic Touch sends compatible taps, holds, swipes, and touchpad drags to the upper screen through Android Accessibility. It does not require Shizuku or Developer options.

1. Open Settings > Connection in Heimdall.
2. Choose Basic Touch and tap its enable action.
3. In Android Accessibility settings, find Heimdall, read the system warning, and enable the service.
4. Return to Heimdall and confirm Basic Touch is available.
5. Test one simple tap macro or touchpad movement before building a longer macro.

Basic Accessibility touch and Thor's built-in mapper use separate touch streams and may cancel each other when used simultaneously. If coexistence is required, use the mapping-compatible Enhanced Touch route only when Heimdall reports it as available.

4. Set Up Shizuku For Controller Enhancement (Optional)

Shizuku is needed for physical-controller recording/replay, Virtual Right Stick, Precision Aim, and mapping-compatible Enhanced Touch. Heimdall does not require root.

• Shizuku official releases
• Shizuku official setup guide

Never Enabled Developer Options Before?

Android menu names can vary slightly by Thor firmware. If a named page is hard to find, use the search box in Android Settings for Build number, Developer options, or Wireless debugging.

1. Open Thor's Android Settings.
2. Open About device, About handheld, or a similarly named page.
3. Find Build number. On some firmware it may be inside a software/version details page.
4. Tap Build number seven times.
5. Enter the screen-lock PIN if Android asks. A message should confirm that Developer options are enabled.
6. Go back to System > Developer options, or search Settings for Developer options.
7. Enable USB debugging.
8. Open Wireless debugging and turn it on.

Developer options are now available. You normally do not need to repeat these eight steps.

Pair And Start Shizuku

1. Install and open Shizuku.
2. Choose Start via wireless debugging, then start pairing.
3. Return to Android's Wireless debugging page.
4. Choose Pair device with pairing code.
5. Enter the displayed code in Shizuku's notification or pairing screen.
6. Return to Shizuku, tap Start, and wait for it to report that Shizuku is running.
7. Open Heimdall > Settings > Connection > Controller Enhancement.
8. Tap the authorize/connect action and allow Heimdall in the Shizuku permission dialog.
9. Return to Heimdall and confirm Controller Enhancement is available.

After restarting Thor, check Shizuku before using controller features. If it is no longer running, start it again; pairing normally does not need to be repeated.

If Shizuku stays on "Searching for pairing service," allow it to run in the background, enable its notifications, keep local networking and wireless debugging available, and try turning wireless debugging off and on once. See the official Shizuku troubleshooting guide for current platform-specific advice.

5. Use Heimdall

Grid And Modules

Open the visual Grid editor to add, drag, resize, or remove modules. Modules snap to the 12 x 8 Grid. Preview first, then save the Grid and Profile explicitly. Layouts from earlier Alpha releases migrate forward; review the result before saving further edits.

Touch Macros

1. Add a Macro module to the Grid.
2. Hold a Macro button for about 1.8 seconds to open the structured editor.
3. Add tap, hold, swipe, or wait steps.
4. When capturing coordinates, act directly on the upper-screen target.
5. Save the Macro, return to Main, and tap the button to run it.

Physical-Controller Macros

Controller recording and replay require Shizuku and an available Controller Enhancement route. Thor's built-in mapper may hide already-mapped physical buttons from Heimdall's recording stream. If this happens, begin recording, temporarily return to Android Home to press the button, then return to Heimdall to review and save the sequence.

Enhanced Touch protects Thor's built-in mapping by default and rejects Macros containing physical-controller steps before replay. If the mapper is off, you may disable that protection for the current Profile; screen steps still use the strict mapping-compatible touch route and never fall back to Accessibility.

Touchpad, Virtual Right Stick, And Precision Aim

• Touch drag converts lower-screen finger movement into an upper-screen drag.
• Virtual Right Stick emits Thor right-stick input through Controller Enhancement and should return to neutral immediately after release.
• Precision Aim is for small camera corrections. Start with low sensitivity and keep the physical stick for large turns.

Magnifier, Maps, Guides, And Canvas

• Add the magnifier to the Grid, accept Android's capture consent, and select the upper-screen region. Hold the module to reselect the region. One live magnifier is supported per Profile, and it cannot run at the same time as screen recording.
• Maps and guides belong to the current Profile and may reference local images, PDFs, text, or an Interactive Map URL.
• Canvas accepts local JPG, PNG, GIF, WebP, and MP4 media. GIF and animated WebP require Android 9 or newer; MP4 is always muted and loops. A Profile can contain multiple independent static Canvases, while GIF, animated WebP, and MP4 share a limit of one dynamic Canvas. Files are limited to 50 MiB; images may be up to 4096 × 4096 and MP4 video up to 2048px on its longest side. APNG is not supported. Double-tap a Canvas for full-screen viewing and hold it to replace its media or adjust composition.

Translation And Hardware Monitor

• Add one Translation module to a Profile, hold it to choose the upper-screen region, OCR script, and target language, then save the component. The runtime region shortcut commits only the confirmed region; it does not save unrelated Grid placement changes.
• Translation uses Heimdall Accessibility screenshots and bundled on-device ML Kit OCR. It does not acquire MediaProjection. Only recognized text is sent over HTTPS to the configured SiliconFlow or custom OpenAI-compatible /chat/completions endpoint.
• Provider settings and the API key are App-global. The API key is encrypted with Android Keystore and is not included in Profile JSON or .heimdall-profile exports.
• Add one Hardware Monitor per Profile to show CPU temperature and used/total RAM. It needs no Shizuku permission and shows unavailable rather than guessing when Thor's verified CPU sensor cannot be read uniquely.

Themes And Joystick Lighting

Choose a registered Heimdall or Freya colorway under Appearance. A Profile can use its own saved theme or follow the App default. The experimental Match joystick lighting switch is App-global and off by default; on supported Thor firmware it applies the resolved theme color and one shared brightness to both joystick rings. Heimdall does not use Shizuku, root, polling, animation, or game events for this feature, and theme changes remain usable if the firmware lighting call is unavailable.

Screenshot And Recording

Quick Actions can capture the upper screen. Recording uses Android MediaProjection and Android Audio Playback Capture rather than microphone input. The upper App may still forbid its game audio from being captured.

6. Back Up Before Uninstalling

Use Profile management to export the current Profile or all Profiles after completing an important layout or Macro setup. The .heimdall-profile bundle is self-contained for supported Profile-owned assets and is validated before import. Heimdall also keeps bounded recovery snapshots for some destructive Profile changes, but these do not replace an export stored outside the App. See the Profile bundle format.

Android platform backup is disabled for this Alpha. Uninstalling the App removes its local data.

Known Alpha Limitations

• Android streaming clients do not reliably forward external Meta/Win input from Heimdall's uinput keyboard. Full Keyboard shows disabled Win keys and Keypad does not offer Win bindings; use the streaming client's built-in keyboard when Win is required.
• Mapping-compatible Shizuku Touch is verified only on tested Thor firmware, game, and mapper combinations. Other firmware may report it unavailable.
• Basic Accessibility touch and Thor's built-in mapper may cancel each other during simultaneous operation.
• Thor's mapper may hide mapped controller buttons from the Macro recorder.
• Only one live magnifier is supported per Profile, and magnification cannot share MediaProjection with recording.
• After a lower-screen Tab round trip, the frozen magnifier's Stop marker can occasionally be missing; stopping can also leave the final retained frame visible. These are known presentation-state issues, not proof that the frame is still live.
• Translation quality, latency, and service availability depend on the selected OCR script, network, model, and provider. SiliconFlow China with Hunyuan-MT-7B is the owner-tested route; other listed or custom OpenAI-compatible endpoints are protocol-compatible but not all are Thor-validated.
• Hardware Monitor reports CPU temperature only when Thor exposes one unique readable cpu-0-1 thermal source to the ordinary App process. It intentionally does not substitute battery temperature or estimate fan speed.
• Theme-matched joystick lighting is experimental, depends on Thor firmware behavior, and remains off by default. A fixed segment near the upper-left of the left joystick may retain a stale/different color or remain lit after Theme, brightness, or switch changes. If this occurs, use Thor's system lighting controls to restore or disable the lights.

Read the v0.3.0-alpha.1 release notes for the complete tested scope, migration notes, and known limitations. The visually reviewed 0.2.0 English and Simplified-Chinese PDF guides remain available as archived references; this README is the current setup guide for 0.3.0.

Helpful Bug Reports

Use GitHub Issues and include:

• Heimdall version and Thor firmware version.
• Controller mode: native or Xbox.
• Game or emulator name.
• Active route: Basic Touch or Shizuku.
• Whether Thor's built-in mapper is enabled.
• Exact reproduction steps and frequency.
• Screenshot or recording when possible.
• Whether restarting Heimdall, restarting Shizuku, or re-authorizing changes the result.

./gradlew :assistant:assembleDebug --no-daemon

./gradlew :assistant:lintDebug --no-daemon

Data, Privacy, And Contributing

Profile data stays on the device unless the player explicitly imports or exports it. Internet access is used for player-configured Interactive Map pages and optional Translation requests. Translation OCR runs locally, but recognized text is sent to the provider selected by the player. See docs/PRIVACY.md.

Read CONTRIBUTING.md before submitting a change. Native input, cross-display routing, MediaProjection, performance, and physical ergonomics require clearly scoped AYN Thor evidence.

License

Heimdall source is licensed under the Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.

AYN and Thor are trademarks of their respective owner. Heimdall is a community project and is not presented as an official AYN application.

Heimdall 0.3.0 Alpha 1 Release Notes

Release tag: v0.3.0-alpha.1

English | 简体中文

English

Update Guidance

• Install 0.3.0-alpha.1 directly over an existing official Heimdall Alpha. Do not uninstall first unless troubleshooting requires it; uninstalling removes local App data.
• Export important Profiles before updating and keep the .heimdall-profile bundles outside the App until the update has been checked.
• Existing 6 x 8 layouts migrate to the 12 x 8 Grid. Review each important Profile before saving further layout changes.
• Translation is optional. It requires Heimdall Accessibility for upper-screen capture plus a player-configured API key and network service; it does not require Shizuku or MediaProjection.

Highlights

• Expanded the Profile Grid from 6 x 8 to 12 x 8 for finer placement while preserving direct drag/resize interaction, preview-first editing, explicit Grid Save, and legacy layout migration.
• Added six governed Heimdall and Freya colorways with shared family materials, semantic states, optional per-Profile theme binding, and a standalone browser Theme Lab for colorway development.
• Added experimental theme-matched Thor joystick lighting. The App-global switch is off by default, uses one shared brightness, and keeps theme behavior independent when the firmware route is unavailable.
• Added one Profile-owned Translation Widget with a selectable upper-screen region, on-device Latin/Chinese/Japanese/Korean ML Kit OCR, target-language control, stable duplicate suppression, and one bounded HTTPS translation request lane. A successful provider connection test now gives visible confirmation.
• Added App-global SiliconFlow China/Global and custom OpenAI-compatible /chat/completions settings. API keys are encrypted with Android Keystore and are excluded from Profile data and exports.
• Added one passive Hardware Monitor per Profile. It reads the uniquely identified ordinary-App cpu-0-1 thermal source and Android RAM information, pauses outside active Main use, and fails closed instead of substituting battery temperature or estimating fan speed. The Freya-family two-row presentation has been compacted without changing the Heimdall-family layout.
• Added GameNative current-state Profile matching for supported PC-game launches, while keeping the conservative resolver, manual-selection protection, and ambiguity-no-switch rule.
• Refined Canvas fill bounds, magnifier interaction, component surfaces, English terminology, compact-control fit, and visual consistency without changing the established Profile/Grid Save boundaries.

Privacy And Network

• Translation screenshots are processed locally for OCR. Heimdall sends recognized text, the requested target language, and a short translation instruction - not the screenshot - to the provider selected by the player.
• Bundled Google ML Kit performs OCR on-device. Google states that the SDK may still send diagnostics and utilization metrics such as device/App information and a per-installation identifier; see the public privacy document for the exact boundary.
• Provider privacy, retention, account, and billing terms apply. Custom endpoints must use HTTPS.
• Translation provider credentials are App-global, encrypted locally, and not included in Profile JSON or .heimdall-profile bundles. See Privacy And Capability Boundary.

Verification Scope

• The registered cumulative Debug baseline is clean at e890301f26f13975d290dbc9fc546e9ce90687d1; its reference APK is SHA-256 81B993139B00367BEF525A9810F06057F21F65DAEBFCA711966A7DA74016B0E7. Later recurrence supersedes that APK's earlier lighting-reliability acceptance but does not invalidate the other accepted baseline features.
• On exact Debug APK SHA-256 3D9BA88D1541232B2A78E1381F8810CA97388CB603B9591EE56FDF65CFA7690B, owner-operated Thor checks accepted the Freya-family Hardware Monitor at two-row height and visible Translation Test Connection success feedback. That APK did not resolve the joystick-lighting defect and was rejected as a complete release candidate.
• Build/static results and accepted Debug APK checks do not accept the real-signed 0.3.0-alpha.1 candidate. Before publication, the exact signed APK must still pass the release-specific Thor update/install, Profile migration, permissions, Translation, Grid, theme, input, magnifier, and cleanup matrix, with the documented experimental-lighting limitation confirmed as bounded and recoverable through Thor's system controls.

Known Limitations

• Heimdall targets AYN Thor and does not guarantee compatibility with every firmware, controller mode, game, emulator, PC streaming client, translation provider, or other dual-screen device.
• Translation accuracy and latency depend on the selected OCR script, game font/layout, network, model, and provider. SiliconFlow China with Hunyuan-MT-7B is the owner-tested provider route; other listed and custom OpenAI-compatible endpoints are protocol-compatible but not all are Thor-validated.
• Only recognized text is sent for translation, but game dialogue, account names, or other selected text may still be sensitive. Select the region deliberately and review the configured provider's terms.
• Hardware Monitor shows CPU temperature only when Thor exposes one unique readable cpu-0-1 thermal source to the ordinary App process. It intentionally reports unavailable on ambiguous or unreadable devices.
• Theme-matched joystick lighting is experimental and off by default. On the tested Thor firmware, a fixed segment near the upper-left of the left joystick can retain a stale/different color or remain lit after Theme, brightness, or switch changes. Turning the feature off inside Heimdall may not clear that segment immediately; use Thor's system lighting controls to restore or disable the lights. This is a known 0.3.0-alpha.1 limitation planned for follow-up investigation.
• Automatic Profile matching remains conservative. RetroArch and PPSSPP Gold retain the previously documented pending/limited coverage; Heimdall does not switch on ambiguous or stale evidence.
• Advanced Controls require Shizuku to be installed, running, and authorized. Unavailable native features fail closed instead of silently changing semantics.
• One live magnifier is supported per Profile, and magnification cannot share MediaProjection with recording.
• Android platform backup remains disabled. Keep exported Profile bundles outside the App before uninstalling or replacing device data.

简体中文

更新说明

• 可将 0.3.0-alpha.1 直接覆盖安装到现有 Heimdall 官方 Alpha。除非排障需要，请勿先卸载；卸载会清除 App 本地数据。
• 更新前请导出重要 Profile，并将 .heimdall-profile 迁移包保存在 App 外部，直到确认更新正常。
• 现有 6 x 8 布局会迁移到 12 x 8 Grid。继续保存布局修改前，请逐一检查重要 Profile。
• 实时翻译是可选功能。它需要 Heimdall 无障碍服务进行上屏捕获，并需要玩家配置 API Key 与网络服务；不需要 Shizuku 或 MediaProjection。

主要改进

• 将 Profile Grid 从 6 x 8 扩展为 12 x 8，提供更细的布局精度，同时保留直接拖动/缩放、先预览、明确保存和旧布局迁移规则。
• 新增六个受治理的 Heimdall/Freya 配色，保持 Family 材质与语义状态一致，支持可选的 Profile 主题绑定，并提供独立浏览器 Theme Lab 供配色开发使用。
• 新增实验性的 Thor 摇杆灯主题匹配。App 全局开关默认关闭，使用统一亮度；固件路线不可用时不影响主题本身。
• 新增每个 Profile 一个实时翻译模块：可选择上屏区域，在本机完成拉丁/中/日/韩 ML Kit OCR，选择目标语言，稳定抑制重复文字，并通过一个有界 HTTPS 请求通道翻译。翻译服务连接测试成功时现在会显示明确反馈。
• 新增 App 全局的 SiliconFlow 中国区/全球区与自定义 OpenAI 兼容 /chat/completions 设置。API Key 使用 Android Keystore 加密，不进入 Profile 数据或导出。
• 新增每个 Profile 一个被动硬件监控模块。它读取普通 App 可访问、唯一识别的 cpu-0-1 温度源和 Android 内存信息；离开活动 Main 后暂停，无法确认时显示不可用，不会拿电池温度代替或估算风扇转速。Freya Family 的两格高度布局已单独压缩，Heimdall Family 布局保持不变。
• 为受支持的 PC 游戏启动路径新增 GameNative 当前状态 Profile 匹配，同时保留保守解析、手动选择保护和歧义时不切换的规则。
• 改进 Canvas 填充边界、放大镜交互、组件材质、英文术语、紧凑控件适配和整体视觉一致性，同时保持既有 Profile/Grid 保存边界不变。

隐私与联网

• 翻译截图只在本机用于 OCR。Heimdall 会把识别出的文字、目标语言和简短翻译指令发送给玩家选择的服务，但不会发送截图本身。
• 内置 Google ML Kit 在本机执行 OCR。Google 说明该 SDK 仍可能发送诊断与使用指标，例如设备/App 信息和每次安装标识符；准确边界见公开隐私文档。
• 翻译服务商自己的隐私、保留、账户和计费条款仍然适用；自定义接口必须使用 HTTPS。
• 翻译服务凭据属于 App 全局设置，在本机加密保存，不会写入 Profile JSON 或 .heimdall-profile 迁移包。详见隐私与能力边界。

验证范围

• 已注册的累计 Debug 基线在 e890301f26f13975d290dbc9fc546e9ce90687d1 保持干净；其参考 APK SHA-256 为 81B993139B00367BEF525A9810F06057F21F65DAEBFCA711966A7DA74016B0E7。后续复现结果已推翻该 APK 对灯光可靠性的早期验收，但不影响基线中其他已接受功能。
• 机主已在 SHA-256 为 3D9BA88D1541232B2A78E1381F8810CA97388CB603B9591EE56FDF65CFA7690B 的精确 Debug APK 上接受 Freya Family 温控模块两格高度显示，以及翻译连接测试成功反馈。该 APK 未解决摇杆灯问题，因此不能作为完整发布候选。
• 编译/静态结果与已接受的 Debug APK 不能替代真实签名 0.3.0-alpha.1 候选包验收。公开发布前仍须在 Thor 上完成该精确签名 APK 的覆盖安装、Profile 迁移、权限、翻译、Grid、主题、输入、放大镜和清理矩阵，并确认已披露的实验性灯光问题范围可控、可通过 Thor 原厂灯控恢复。

已知限制

• Heimdall 面向 AYN Thor，不保证兼容所有固件、手柄模式、游戏、模拟器、PC 串流客户端、翻译服务或其他双屏设备。
• 翻译准确度与延迟取决于 OCR 文字类型、游戏字体/布局、网络、模型和服务商。机主验证的服务路线是 SiliconFlow 中国区配合 Hunyuan-MT-7B；其他列出的服务和自定义 OpenAI 兼容接口属于协议兼容，并非都完成 Thor 实机验证。
• 翻译只发送识别出的文字，但游戏对话、账户名或选区中的其他文字仍可能敏感。请谨慎选择区域，并查看所配置服务商的条款。
• 只有当 Thor 向普通 App 暴露唯一、可读的 cpu-0-1 温度源时，硬件监控才显示 CPU 温度；来源歧义或不可读时会明确显示不可用。
• 主题匹配摇杆灯为实验性功能，默认关闭。在已测试的 Thor 固件上，切换主题、亮度或开关后，左摇杆左上附近的一处固定灯段可能残留旧色、显示异色或继续亮起；在 Heimdall 内关闭功能也不一定立即清除。遇到异常时请使用 Thor 原厂灯光设置恢复颜色或关闭灯光。此问题作为 0.3.0-alpha.1 已知限制保留，后续版本将继续调查。
• Profile 自动匹配继续采用保守策略。RetroArch 与 PPSSPP Gold 保留此前记录的待验证/有限覆盖；Heimdall 不会根据歧义或陈旧证据切换。
• 高级控制要求 Shizuku 已安装、运行并授权。原生能力不可用时会明确关闭，不会静默切换为语义不同的路线。
• 每个 Profile 当前只支持一个实时放大镜；放大镜不能与录屏共享 MediaProjection。
• Android 平台备份仍处于关闭状态。卸载或替换设备数据前，请把导出的 Profile 迁移包保存在 App 外部。

Build integrity

• Source commit: 086e2235e4b429cdb7417bf79b4e399f479e0eaa
• Package: com.mastercook777.heimdall
• Version code: 7
• Version: 0.3.0-alpha.1
• Signing certificate SHA-256: 7B779E4A082DDBC00FF47706B3B3A9E91B2594E33EA39DFE1376E1DBA538F458
• APK SHA-256: 0fd9949ba9f5533a317226a7b043e1c84f5922cea0a8fe28d95d8a65447c00b7