{"id":34547843,"url":"https://github.com/mensfeld/hotspotchi","last_synced_at":"2025-12-24T07:31:29.931Z","repository":{"id":327911889,"uuid":"1111602370","full_name":"mensfeld/hotspotchi","owner":"mensfeld","description":"Tamagotchi Uni WiFi hotspot for Raspberry Pi - meet all 100+ Tama Search characters at home!","archived":false,"fork":false,"pushed_at":"2025-12-10T07:49:32.000Z","size":4258,"stargazers_count":13,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-10T09:57:23.792Z","etag":null,"topics":["raspberry-pi","raspberry-pi-3","raspberry-pi-4","tamagotchi","tamagotchi-game","tamagotchi-uni"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mensfeld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T09:25:29.000Z","updated_at":"2025-12-10T07:49:35.000Z","dependencies_parsed_at":"2025-12-10T10:05:01.088Z","dependency_job_id":null,"html_url":"https://github.com/mensfeld/hotspotchi","commit_stats":null,"previous_names":["mensfeld/hotspotchi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mensfeld/hotspotchi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensfeld%2Fhotspotchi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensfeld%2Fhotspotchi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensfeld%2Fhotspotchi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensfeld%2Fhotspotchi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mensfeld","download_url":"https://codeload.github.com/mensfeld/hotspotchi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensfeld%2Fhotspotchi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27997308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["raspberry-pi","raspberry-pi-3","raspberry-pi-4","tamagotchi","tamagotchi-game","tamagotchi-uni"],"created_at":"2025-12-24T07:31:29.814Z","updated_at":"2025-12-24T07:31:29.918Z","avatar_url":"https://github.com/mensfeld.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hotspotchi\n\n![Hotspotchi](misc/banner.png)\n\n[![CI](https://github.com/mensfeld/hotspotchi/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/hotspotchi/actions/workflows/ci.yml)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nCreate WiFi access points with custom MAC addresses and SSIDs for meeting characters in Tamagotchi Uni's **Tama Search** feature.\n\n## Why Hotspotchi?\n\nThe Tamagotchi Uni's **Tama Search** feature lets you meet special characters by detecting nearby WiFi networks. The character you encounter depends on the last two bytes of the WiFi access point's MAC address, or in some cases, specific SSIDs for event-exclusive characters.\n\nThe problem? You'd need to physically visit different locations with different WiFi networks to collect all characters - or wait for special real-world events that may never happen in your area.\n\n**Hotspotchi solves this** by turning your Raspberry Pi into a WiFi hotspot that can spoof any MAC address or SSID, letting you:\n\n- Meet all ~100 characters from home without traveling\n- Access event-exclusive characters (like Sanrio collaborations) that require specific SSIDs\n- Automatically rotate through characters daily, or cycle through the entire collection\n- Track which characters you've encountered via the web dashboard\n\nPerfect for completionists, rural players without access to many WiFi networks, or anyone who just wants to meet their favorite Tamagotchi characters without leaving the house.\n\n![Hotspotchi Web Dashboard](misc/ui.png)\n\n## Features\n\n- **80 MAC-based characters** - Meet different Tamagotchi characters by changing the WiFi MAC address (includes seasonal characters)\n- **21 special SSID characters** - Access event-exclusive characters with special network names\n- **Multiple rotation modes**:\n  - `daily_random` - Different character each day, same all day (default)\n  - `random` - New random character each boot\n  - `cycle` - Progress through all characters in order\n  - `fixed` - Always show a specific character\n  - `disabled` - Use device default MAC\n- **Seasonal filtering** - Only selects characters available in the current season\n- **Web dashboard** - Monitor and control via browser\n- **Raspberry Pi optimized** - Works with hostapd + dnsmasq\n\n### How Daily Random Works\n\nThe `daily_random` mode uses a date-based seed to select a character. This means:\n- **Same character all day** - The same character is selected throughout the entire day\n- **Changes at midnight** - A new character is selected when the date changes\n- **Deterministic** - If you restart the service, you'll get the same character for that day\n- **Pool of ~100** - By default, both MAC-based (80) and special SSID characters (21) are included in the rotation\n\nThis design ensures a consistent experience throughout the day while still providing variety over time.\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/mensfeld/hotspotchi.git\ncd hotspotchi\n\n# Run the installer\nsudo bash scripts/install.sh\n```\n\nThe installer will set up everything automatically, including systemd services for auto-start.\n\n## Security\n\n**Hotspotchi requires root privileges** to manage network interfaces and system services.\n\nThe WiFi network is secured by default:\n- A random 16-character password is generated daily\n- Tamagotchi only needs to *detect* the network name, not connect to it\n- The password prevents random devices from joining your hotspot\n\nYou can set a fixed password or open network in the config if needed, but the default is recommended.\n\n## Usage\n\nAfter installation, both the hotspot and web dashboard run automatically as systemd services.\n\n### Systemd Services\n\n```bash\n# Check status\nsudo systemctl status hotspotchi\n\n# View logs\njournalctl -u hotspotchi -f\n\n# Restart after config changes\nsudo systemctl restart hotspotchi\n```\n\n### Web Dashboard\n\nAccess at `http://raspberrypi.local:8080` (or your Pi's IP address).\n\nThe dashboard shows:\n- Current SSID and MAC address\n- Active character name\n- Countdown to next character (daily mode)\n- Searchable character browser\n- Special SSID selector\n- Character exclusion controls\n\n### Character Exclusions\n\nWant to keep the \"discovery\" aspect of Tama Search? You can exclude specific characters from the rotation modes (daily_random, random, cycle), so you won't encounter them at home.\n\n**Via Web Dashboard:**\n- Hover over any character and click the `-` button to exclude it\n- Excluded characters show with an `X` badge and appear faded\n- Use the filter dropdown to view \"Excluded Only\" or \"Available Only\"\n- Click \"Include All\" to reset all exclusions\n\n### Command Line (Optional)\n\nFor troubleshooting or manual control:\n\n```bash\n# List all characters\nhotspotchi list-characters\n\n# List special SSIDs\nhotspotchi list-ssids\n\n# Interactive menu\nsudo hotspotchi interactive\n\n# Manual start (not needed if using systemd)\nsudo hotspotchi start\n```\n\n## Configuration\n\nEdit `/etc/hotspotchi/config.yaml`:\n\n```yaml\n# WiFi interface (usually wlan0 on Raspberry Pi)\nwifi_interface: wlan0\n\n# Concurrent mode: run hotspot while staying connected to home WiFi\n# Requires compatible WiFi chipset (Pi 3B+/4/5 typically support this)\nconcurrent_mode: false\n\n# SSID mode: normal, special, or custom\nssid_mode: normal\ndefault_ssid: Hotspotchi\n\n# MAC mode: daily_random, random, cycle, fixed, or disabled\nmac_mode: daily_random\n\n# Include special SSID characters in random rotation (default: true)\ninclude_special_ssids: true\n\n# For fixed mode - character index (0 = Mametchi)\nfixed_character_index: 0\n\n# For special mode - SSID index (0 = Angel \u0026 Devil)\nspecial_ssid_index: 0\n\n# Web server settings\nweb_host: \"0.0.0.0\"\nweb_port: 8080\n```\n\n## How It Works\n\n### With Tamagotchi Uni\n\n1. Start the Hotspotchi hotspot on your Raspberry Pi\n2. On your Tamagotchi Uni, go to **Tama Search**\n3. Select the network when it appears\n4. Meet the character determined by the current MAC/SSID!\n\n### MAC-Based Characters\n\nCharacters are determined by the last two bytes of the MAC address. Hotspotchi uses the format:\n\n```\n02:7A:6D:A0:XX:YY\n```\n\nWhere:\n- `02` = Locally administered unicast address\n- `7A:6D:A0` = \"TAMA\" signature\n- `XX:YY` = Character identifier\n\n### Special SSIDs\n\nSome characters are triggered by specific WiFi network names (SSIDs) that were originally only available at special events in Japan. Hotspotchi includes 21 known special SSIDs:\n\n- **Angel \u0026 Devil** - World Tamagotchi Tour\n- **Makiko** - Bandai Cross stores\n- **1123 Mametchi** - 28th Anniversary event\n- And more! Run `hotspotchi list-ssids` for the full list.\n\n### Seasonal Characters\n\nSet your Tamagotchi's date to meet seasonal characters:\n\n| Season | Months | Characters |\n|--------|--------|------------|\n| Spring | Mar-May | Rosetchi, Yotsubatchi, Hanafuwatchi, Musiharutchi |\n| Summer | Jun-Aug | Acchitchi, Tokonatchi, Tropicatchi, Yashiharotchi |\n| Fall | Sep-Nov | Dekotchi, Youngdrotchi, Witchi, Pumpkitchi |\n| Winter | Dec-Feb | Amiamitchi, Santaclautchi, Akahanatchi, Yukipatchi |\n\n## Troubleshooting\n\n### Raspberry Pi becomes unreachable after starting hotspot\n\n**This is expected behavior.** When Hotspotchi starts the WiFi hotspot, it takes over the `wlan0` interface. If your Pi was connected to your home WiFi via `wlan0`, it will disconnect.\n\n**Solutions:**\n\n1. **Use Ethernet for management** (recommended) - Connect your Pi via Ethernet cable before starting the hotspot\n\n2. **Enable concurrent mode** (Pi 3B+/4/5) - Run hotspot while staying connected to your home WiFi:\n   ```yaml\n   # /etc/hotspotchi/config.yaml\n   concurrent_mode: true\n   ```\n\n3. **Use a second WiFi adapter** - Add a USB WiFi adapter for your home network\n\n### WiFi not appearing\n\n```bash\n# Check service status\nsudo systemctl status hotspotchi\n\n# Check for errors\njournalctl -u hotspotchi -n 50\n\n# Unblock WiFi if blocked\nsudo rfkill unblock wifi\n```\n\n### Tamagotchi doesn't see the hotspot (concurrent mode)\n\n**Tamagotchi Uni only supports 2.4GHz WiFi.** In concurrent mode, the hotspot must use the same channel as your home WiFi connection. If your Pi is connected to a 5GHz network, the hotspot will also be on 5GHz and your Tamagotchi won't see it.\n\n**Solutions:**\n\n1. **Connect your Pi to a 2.4GHz network** - Most routers broadcast both bands. Connect to the 2.4GHz one (often has \"2.4G\" in the name or is on channels 1-14).\n\n2. **Disable 5GHz on the Pi:**\n   ```bash\n   # Create config to prefer 2.4GHz\n   sudo bash -c 'echo \"options cfg80211 ieee80211_regdom=US\" \u003e /etc/modprobe.d/disable-5ghz.conf'\n\n   # Set regulatory domain\n   sudo iw reg set US\n\n   # Reboot\n   sudo reboot\n   ```\n\n3. **Verify you're on 2.4GHz:**\n   ```bash\n   iw wlan0 info | grep channel\n   # Channels 1-14 = 2.4GHz, channels 36+ = 5GHz\n   ```\n\n**Note:** In normal (non-concurrent) mode, Hotspotchi defaults to channel 7 (2.4GHz), so this issue doesn't apply.\n\n**Channel 12-14 issue:** Even on 2.4GHz, channels 12-14 may not work. Many devices (especially US-region phones and Tamagotchis) only support channels 1-11. If your router uses channel 12, 13, or 14, configure it to use a lower channel (1-11) or run Hotspotchi in non-concurrent mode which defaults to channel 7.\n\n## FAQ\n\n### Can I run Hotspotchi on my regular computer instead of a Raspberry Pi?\n\nHotspotchi can technically run on any Linux machine with a WiFi adapter that supports Access Point (AP) mode, but **Raspberry Pi is strongly recommended** because:\n\n1. **AP mode support** - Many desktop/laptop WiFi cards don't support AP mode. Raspberry Pi's built-in WiFi does.\n2. **Always-on operation** - The Pi can run 24/7 with minimal power consumption. You probably don't want to keep your desktop running just for Tamagotchi.\n3. **Tested platform** - The install scripts and documentation are designed for Raspberry Pi OS.\n4. **Dedicated device** - A Pi can sit near your Tamagotchi play area without tying up your main computer.\n\nIf you want to try on a desktop Linux machine, check if your WiFi supports AP mode:\n```bash\niw list | grep -A 10 \"Supported interface modes\" | grep \"AP\"\n```\n\nIf \"AP\" appears in the output, it might work - but you're on your own for setup.\n\n## Updating\n\n```bash\ncd ~/hotspotchi\nsudo bash scripts/upgrade.sh\n```\n\n## Uninstallation\n\n```bash\nsudo bash scripts/uninstall.sh\n```\n\n## Contributing\n\nContributions are welcome! Characters are stored in `src/hotspotchi/data/characters.yaml` for easy editing.\n\n**To add a MAC-based character:**\n\n```yaml\n- byte1: 0x04\n  byte2: 0x00\n  name: NewCharacter\n  season: spring  # Optional\n```\n\n**To add a special SSID character:**\n\n```yaml\n- ssid: YourSSIDString32CharsLong1234567\n  character_name: Character Name\n  notes: Where this SSID was discovered\n  active: true\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Tamagotchi community for discovering MAC/SSID mappings\n- [Tamagotchi Wiki](https://tamagotchi.fandom.com/) for character information\n- Everyone who shared special event SSIDs\n\n## Disclaimer\n\nThis project is not affiliated with or endorsed by Bandai. Tamagotchi is a registered trademark of Bandai.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmensfeld%2Fhotspotchi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmensfeld%2Fhotspotchi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmensfeld%2Fhotspotchi/lists"}