Emuiibo Switch

emuiibo
General
Author	XorTroll
Type	Overlays
Version	1.0.0
License	GPL-2.0
Last Updated	2023/05/05
Links
Download
Website
Source
Support Author

emuiibo is a background process (and service) which Nintendo Switch's internal NFC (NFP) services to support virtual amiibo emulation.

Installation

You need to the following files:

• emuiibo (grab the latest release here)
• emutool (see emuiibo download above)
• Tesla (grab the latest Tesla-Menu and nx-ovlloader)

How to setup:

• Make sure you downloaded all files mentioned above.
• Create these folders on your SD (if not present):
  • sd:/emuiibo/amiibo
  • sd:/switch/.overlays
• Extract all ZIP files and copy the folders on your SD card. It should look like this in the end:
  • emuiibo - sd:/atmosphere/contents/0100000000000352/exefs.nsp and /flags folder
  • emuiibo overlay - sd:/switch/.overlays/emuiibo.ovl
  • tesla-menu - sd:/switch/.overlays/ovlmenu.ovl
  • nx-ovlloader - sd:/atmosphere/contents/420000000007E51A/exefs.nsp and /flags folder

If you set up everything correctly, emuiibo is ready to load your amiibos you created via emutool (see below) or via raw .bin amiibo dump fules.

User guide

SD layout

• Emuiibo's directory is sd:/emuiibo.

• Virtual amiibos go inside sd:/emuiibo/amiibo. For instance, an amiibo named MyMario would be sd:/emuiibo/amiibo/MyMario/<amiibo content>.

• However, categories are supported by placing amiibos inside sub-directories (only inside a directory, like 3DS menu categories inside categories are not supported) - for instance: sd:/emuiibo/amiibo/SSBU/Yoshi would be a Yoshi amiibo inside SSBU category.

• A virtual amiibo is detected by emuiibo based on two aspects: a amiibo.json and a amiibo.flag file must exist inside the virtual amiibo's folder mentioned above. If you would like to disable a virtual amiibo from being recognised by emuiibo, just remove the flag file, and create it again to enable it.

• Every time the console is booted, emuiibo saves all the miis inside the console to the SD card. Format is sd:/emuiibo/miis/<index> - <name>/mii-charinfo.bin.

emutool - creatw virtual amiibo (PC)

Emuiibo no longer accepts raw BIN dumps to emulate amiibos. Instead, you can use emutool PC tool in order to generate virtual amiibos.

First we look on the left half of the program:

• In the first dropdown menu on top, you can choose amiibos from a certain collection.
• In the second dropdown menu next to it, you can choose any amiibo you want to create.

On the right half of the tool:

• You can choose a name for the amiibo you want to create, a custom directory name (if you uncheck "Use name as directory name" below it).
• You can then choose if you want the amiibo to use randomized UUIDs. This means that the console always read it as a new/unique amiibo (some games have restrictions to use the same amiibo only once or once a day). Note that this might cause issues for games which save data into amiibos, so avoid using it on those.
• Then, you can choose if you want to save the amiibo picture shown on the left into the amiibo folder (it will be saved as a PNG file).

Optional:

• If you have a FTP connection on your switch console, you can directly save your amiibo on your SD into: emuiibo/amiibo/.

In the last step you click on "Create virtual amiibo" and choose a location, where you want to save it to. If an SD card with emuiibo is detected, the program will point to that SD's /emuiibo/amiibo folder.

Now you can copy the generated amiibo folder onto your SD card, in sd:/emuiibo/amiibo/ or sd:/emuiibo/amiibo/<category>/ - you can sort virtual amiibos by categories this way.

emuiibo basic controls

If you set up everything mentioned above, you're ready to use emuiibo ingame.

Tip: Enable it before you start a game, because it does not work in some games if you enable it after launching the game.

To open the Tesla overlay, hold down L1 + D-Pad Down and then press R3 (Right Stick). If you did it, Tesla Overlay will open on the left side of the screen. Now choose emuiibo.

In the emuiibo overlay:

• Manage emulation: enable/disable emuiibo via DPad or L3 (it´s disabled by default).
• View amiibo:
  • Choose your amiibo from root (sd:/emuiibo/amiibo/).
  • Choose your amiibo from a category (sd:/emuiibo/amiibo/<category>/).

To go back in the menus, just press B button.

After you selected an amiibo, you can see it's selected on top in the overlay and that it is "connected".

"Connected" is the equivalent of holding a real amiibo figurine/card on the NFC point. To "Disconnect" the amiibo (the equivalent of removing a real amiibo from the NFC point), just select the same amiibo again.

To see if emuiibo is working ingame, check if emuiibo is intercepting the game when it's trying to access amiibos. If it's not, try launching the game with emuiibo enabled first.

Example usage

• Open the overlay and choose emuiibo.
• Enable emuiibo.
• Start the game.
• Navigate to the games NFC feature to use the amiibo and activate it.
• Open the overlay and choose your amiibo (will be connected).
• The game should now register/make use of it.
• If the game tells you to remove the amiibo, disconnect it.

Options

• Emulation status (on/off):
  • When emuiibo's emulation status is on, it means that any game trying to access/read amiibos will be intercepted by emuiibo.
  • When it's off, it means that amiibo services will work normally, and nothing will be intercepted.
  • This is basically a toggle to globally disable or enable amiibo emulation.

• Active virtual amiibo:
  • It's the amiibo which will be sent to the games which try to scan amiibos, if emulation is on.
  • Via tools such as the overlay, one can change the active virtual amiibo.

• Virtual amiibo status (connected/disconnected):
  • When the active virtual amiibo is connected, it means that the amiibo is always "placed", as if you were holding a real amiibo on the NFC point and never moving it - the game always detects it.
  • When it is disconnected, it means that you "removed" it, as if you just removed the amiibo from the NFC point.
  • Some games might ask you to remove the amiibo after saving data, so you must disconnect the virtual amiibo to "simulate" that removal.
  • This is a new feature in v0.5, which fixed errors, since emuiibo tried to handle this automatically in previous versions, causing some games to fail.

All this aspects can be seen/controlled via the overlay.

Supported figures

Some games (like Skylanders) make use of their particular NFC technology, aside from amiibos.

This project ONLY emulates amiibos; therefore, in Skylanders' case, only the two special figurines with amiibo support can be emulated here, where emuiibo will only emulate the "amiibo part" of them.

For developers

emuiibo hosts a custom service, also named emuiibo, which can be used to control amiibo emulation by IPC commands.

The overlay's code can be a good example to see how to control emuiibo from IPC and C++.

Raw dumps and encryption

When using raw dumps, emuiibo doesn't save everything they have onto the new format, since some bits are encrypted. This is, for instance, why 20-heart Wolf Link amiibo dumps won't work with emuiibo, since the amiibo's app-area, where the console/game saves amiibo savedata, is an encrypted field, and it contains the information BOTW needs in order to recognize the feature.

You can manually extract it, using amiitool. You'll need to find the retail amiibo key to use it.

Running the following will decrypt the raw dump:

amiitool -d -k <key-file-bin> -i <amiibo-raw-dump-bin> -o <out-decrypted-bin>

You'll have the decrypted app-area section at offset 0xDC on the decrypted dump, of length 0xD8. By saving that as <game-access-id>.bin inside the /areas folder of a virtual amiibo being used by emuiibo, you can actually import the dump's savedata, which would allow for such things to work. Check below for a list of per-game access IDs.

Amiibo format

Amiibos are, as stated above, directories with an amiibo.json and an amiibo.flag file. The flag is mainly there in case people would like to disable an amiibo and then re-enable it later.

The JSON file contains all the aspects and data an amiibo needs to provide to games, except a few aspects (per-game savedata, protocol and tag type...)

This are the properties an amiibo has:

Name	The amiibo's name (max. 40 characters).
UUID	It's a unique identifier for the amiibo, composed of 10 bytes. If the "uuid" field is not present in the JSON, emuiibo will randomize the UUID everytime amiibo data is sent to a game. This has potential benefits in certain games, like in BOTW, where amiibos can only be used once per day, but with randomized UUIDs this can be bypassed, and one can get infinite rewards scanning this amiibo infinite times.
Mii	Every amiibo has a mii associated with it (it's "owner"). Internally, miis consist on a 88-byte structure known as "charinfo", so emuiibo stores this data in a file (typically mii-charinfo.bin). For new amiibos, emuiibo uses the console's services to generate a random mii, but for those who would like to use a mii from their console, emuiibo dumps in miis directory the console's miis, so it's just a matter of copying and pasting/replacing charinfo bin files. NOTE: emuiibo contains the charinfo file's name in the JSON (mii_charinfo_file), so if the file ever gets renamed, don't forget to rename it in the JSON too, or emuiibo will generate a random mii for the file name in the JSON.
First and last write dates	These are (as if it wasn't obvious) the first and last time the amiibo was written/modified. When a virtual amiibo is created with emutool, the current date is assigned to both dates, and when the amiibo is modified in console, emuiibo updates the last write date.
Write counter	This is a number which is increased everytime the amiibo is modified (and emuiibo does so, imitating Nintendo), but when the number reaches 65535, it is no longer increased (the number is technically a 16-bit number).
Version	This value technically represents the version of Nintendo's amiibo library (NFP), so emuiibo just defaults it to 0.

Areas

Areas (application areas, technically) are per-game amiibo savedata. Technically, real amiibos can only save data for a single game, but emuiibo allows as many games as you want (since savedata is stored as files). This savedata is quite small, and tends to be 216 bytes or smaller.

emuiibo saves this data inside bin files at areas directory inside the amiibo's directory, and the bin file's name is the game's area access ID in hex format.

An access ID is a unique ID/number each game has for amiibo savedata, used to check if the game actually has savedata in an amiibo. Here's a list of games and their access IDs:

Per-game access IDs

A list is maintained at Switchbrew.

Screenshots

emuiibo

emutool

Media

How to use emuiibo with Tesla in switch - switch 10.2.0 Atmosphere 0.14.4 Animal crossing (TruganiniGamePlay)

Changelog

v1.0.0 2023/05/05

• This update's major milestone (among others) is to finally intercept nfp:sys service, AKA intercepting system settings/applet amiibo support - hence, many changes here are because of this
• emuiibo is no longer a pre-release, by the way ;)

NOTE: don't forget to update to the latest nx-ovlloader/Tesla menu!

• The virtual amiibo format went through some major changes system-settings support required:
  • Now area information is saved in <amiibo>/areas.json, which stores pairs of access_id and program_id values. System settings support also requires knowing the program ID of the title using the area, which is why now area information is saved here
  • This JSON also contains a current_area_access_id field: system settings's option to delete an amiibo's save data conflicts with emuiibo's implementation of saving (real amiibos have a single game save data while emuiibo allows multiple), so this field contains the currently "selected" area, which consists on the area system settings will see and show info of/delete
  • In order to convert old formats to this new changes, the areas.json file will be created automatically, but since there is no way for emuiibo to tell the program ID of plain amiibo areas, it will set a certain ID by default (to be distinguishable from the rest, I opted for "Retain Interactive Display Menu"'s one, which is a debug program), and for the correct ID to be set on the area info, the user must use the amiibo with the game in question. I know this can be a bit tedious, but it's the best way to handle it
  • Now virtual amiibos with names longer than 10 characters are ignored and considered as invalid. Due to certain technical reasons (and Nintendo being too inconsistent with its formats) I originally thought the limit was at 40, but in certain contexts (like system settings) where the 10-char limit is imposed, existing virtual amiibos with longer names tend to cause weird/unexpected behavior
  • The system settings formatting option will remove all virtual amiibo areas (won't unregister it like with real amiibos since virtual amiibos have no concept of being (un)registered)
  • The system-settings game-save-deleting option will remove the selected amiibo area, which can be changed from the overlay. This selected area will also be the one system-settings always shows
  • Now the random-UUID option has its own field in the amiibo.json file (use_random_uuid), so that amiibos will have their own UUID which won't be cleared when random-UUID wants to be enabled (see related overlay changes)
• Old formats supported in older emuiibo versions (raw bin dumps and older virtual amiibos) are fully supported now! Backwards-compatibility has been reimplemented so that these outdated formats are automatically converted to the modern format on boot (for bin dumps, the dump binary file gets moved but not deleted)
  • Criptography is now supported, so that if /switch/key_retail.bin is present, the encrypted sections of bin dumps will be accessible by emuiibo, so that the resulting converted amiibos will contain all the amiibo data present there (this includes game app-data areas, AKA amiibo game save-data)

emuiibo

• Compiled with latest libraries
• All the format changes above resulted in code changes to support it, of course
• The emuiibo IPC service (used by the overlay and other homebrew to control emuiibo) has some new commands reflecting the format changes. As always, the overlay is the best example of a homebrew using this service to control amiibo emulation
• Some amiibo ID internal bugs were fixed (again, huge shoutout to Nintendo for being unnecessarily and heavily inconsistent with their amiibo formats across platforms), which would've previously caused some isssues with certain games (like Monster Hunter Rise, Splatoon, etc.)

overlay

• Compiled with latest libtesla/libnx
  • A long-standing libtesla UI cleanup bug was fixed which may have caused crashes sometimes
• The UI was extended (following the new format changes) to show/toggle the currently selected area of the active virtual amiibo, as well as to toggle amiibos' random UUID option
• Listed amiibo/plain directory entries are now alphabetically ordered
• If the title is installed, it's name will be shown; otherwise, it's plain program ID will be shown
• emuiibo's version is now checked, so that an overlay will refuse to work with older/newer emuiibo versions and thus only work with the exact same version
• French language support was added

emutool

• .NET framework version was lowered to v4.5.2, hoping this may increase compatibility with certain systems
• Amiibos whose default name contains "/" are replaced with "_", and special characters are also replaced with their ASCII equivalents (like E from È) to avoid issues with system paths on virtual amiibo creation

v0.6.3 2022/02/11

• emuiibo:
  • Fixed some minor issues related to virtual amiibo area saving.
  • Fixed a weird internal issue where sometimes emuiibo would become unaccessible under certain circumstances.
• overlay:
  • The overlay has almost entirely changed thanks to the huge work of AD2076 and AmonRaNet:
    • Really improved UI and design.
    • Now, aside from English, the following languages are supported: German, Spanish, Russian, Traditional and Simplified Chinese.
• emutool:
  • No changes (not uploading a new release).

v0.6.3 2021/04/20

• emuiibo:
  • Fixed support for latest Atmosphere versions (0.19.x) and for 12.x system updates. Note that this emuiibo version (and next ones) won't work on older Atmosphere versions.
• emutool:
  • No changes, only the version value was updated.

v0.6.2 2021/02/04

• (emutool didn't change for this new release, only the version number was updated.)
• emuiibo:
  • Small nx library corrections/improvements.
  • Atmosphere 0.18.0 support (always use emuiibo with latest ams if it's supported!).

v0.6.1 2020/10/28

• emuiibo:
  • Fixed controller support - some games couldn't be used with detached JoyCons / other controllers on v0.6, that has been fixed on this version.
  • When exporting system miis on startup, now emuiibo doesn't use the mii's name as the mii folder's name, the mii's name is written to a name.txt file instead to avoid potential FS issues with non-UTF8 names, and the mii folder's name will just be an index.
• emutool:
  • Added support for creating all available virtual amiibos at once - they will be organized in folders according to their series.

v0.6 2020/09/26

• emuiibo has been through a complete rewrite in Rust (except for the overlay), so everything has changed internally:
  • Support for latest Atmosphere (0.14.4), and next releases unless breaking changes are introduced.
  • emuiibo no longer handles conversion of raw amiibo dumps or old emuiibo formats - only the current format is supported (the one used since 0.5.x).
  • Heap size has been considerably reduced (last version used 0x40000, current one only uses 0x4000) - in addition, the exefs NSP's size has been reduced too, being now 5 times smaller than 0.5.x.
  • Regarding the known issues with time services and sysmodules, emuiibo no longer makes use of this service to avoid creating more issues, even though this implies that virtual amiibos' "last write date" won't be set when a virtual amiibo is modified - luckily, not emulating this anymore doesn't change anything relevant nor break anything.
  • emuiibo's IPC interface other processes may use to communicate with it has a minor change - thus, 0.5.x or older overlays WON'T WORK with this version's emuiibo.
• emutool did not change at all.

v0.5.1 2020/06/21

• Note: this is nothing more than a quick update in order to support latest CFW - emutool wasn't even updated, the only thing which changed is its version number, and emuiibo has no relevant changes other than small bugfixes.
• Updated libnx, libstratosphere/Atmosphere-libs and JSON libraries. emuiibo requires C++20 now, as Atmosphere-libs do so.
• Changed size from 0x20000 to 0x40000 to avoid some memory issues people experienced.
• Fixed a small bug when dumping console miis to the SD card on startup.

v0.5 2020/04/17

• Latest Atmosphere (0.11.1) and 10.0.0 support.
• New virtual amiibo format, consisting on a single JSON file (emuiibo will automatically convert old formats to this new format on startup).
• emuiibo:
  • emuiibo has been completely rewritten, and this has been incredibly helpful, since almost any issue present for previous versions is no longer a problem/
  • Key combos are no longer a thing, since they were a not very friendly way of controlling emuiibo, and having an overlay is 100 times more helpful.
  • The way emuiibo internally "mimics" Nintendo's amiibo services has been improved a lot. This was what caused many games to not work fine (Link's Awakening, Diablo 3, Fire Emblem...). In fact, emuiibo is introducing a new feature which makes amiibo emulation slightly more similar to real amiibos, which made those specific games work (see below).
  • Virtual amiibo connecting/disconnecting: these two are the equivalents of placing a real amiibo in the NFC point/R-stick (connecting it) and removing it from that spot (disconnecting it). Previously, emuiibo "tried" to take care of that manually (games like SSBU asked the user to remove the amiibo after saving progress), which resulted in many games freezing when they read amiibos. Now, simply disconnect the amiibo when you need to remove it, and connect it to use it again.
  • Support for raw bin amiibo dumps works now (it was broken for v0.4).
  • Old (v0.3.x and v0.4) amiibo formats are converted on startup, so no need to create new amiibos, old ones should work.
  • IPC API changed completely, check the overlay's source as an example of how it works.
  • Now logs are reset on each reboot, so make sure to not reboot or make a copy of emuiibo's log file if wou want to preserve them! (this was done since the log file would get excessively big if it wasn't cleaned).
• [NEW] Tesla overlay:
  • This is a new addition to the project and, probably, the best and easiest way of controlling emuiibo (thanks to WerWolv for such an amazing project).
  • This are its current features:
    • Toggle on/off emulation.
    • Control virtual amiibo emulation with emuiibo, select a virtual amiibo as active, connect/disconnect it (see above).
    • Browse through categories, keep your virtual amiibos organized.
    • See in real time if the currently opened game is being intercepted by emuiibo (if you have the overlay open while the game runs, you might be able to spot the exact instant in which emuiibo intercepts the game's amiibo access).
• emutool:
  • Saving virtual amiibos to FTP is now supported.
  • Fixed a bug where amiibos with the same name would make the program fail.
  • Added support to save amiibos using the last location selected to save the previous amiibo, instead of having to select it again (can be quite useful when making many virtual amiibos).
  • Virtual amiibo name and the virtual amiibo's directory name are now different settings (they used to be treated as the same field before).
  • An option has been added to save the amiibo's image as a PNG file (amiibo.png), overlay might add support to display it in next versions ;)
  • Added help option, which will point to emuiibo's repository's README.
  • [Silent update] fixed a bug in certain cases where emutool would fail to connect to AmiiboAPI (WebException).
• FAQ:
  • Can I use 20 hearts link wolf amiibo bin dump with emuiibo?
    • Since BOTW detects the 20 hearts in the link wolf amiibo via amiibo savedata, which emuiibo can't access on bin dumps since it's encrypted and we don't yet support decryption, you will need to extract manually the savedata from your PC (using tools like amiitool) for now.
  • Games which needed emuiibo to be on before they were launched (BOTW) are or will ever be fixed?
    • No - sadly there's nothing to be fixed here. It's just how the game uses amiibo services - these games initialize amiibo services the moment they're launched, so emuiibo needs to be on at that moment to enable emulation in that game.

Credits

• Everyone who contributed to the original nfp-mitm project (forks): Subv, ogniK, averne, spx01, SciresM.
• libstratosphere project and libraries.
• AmiiboAPI web API, which is used by emutool to get a proper, full amiibo list, in order to generate virtual amiibos.
• 3DBrew for their detailed documentation of amiibos, even though some aspects are different on the Switch.
• LoOkYe for writing emuiibo's wiki and helping with support.
• AD2076 and AmonRaNet for helping with the tesla overlay.
• AmonRaNet for all the work he put into the overlay.
• AmonRaNet, Impeeza, amazingfate, qazrfv1234, shadow2560 and SimoCasa for providing/helping with translations.
• Thog / Ryujinx devs for reversing mii services and various of its types.
• Citra devs for several amiibo formats used in 3DS systems.
• Manlibear for helping with improvements and development of emutool.
• All the testers and supporters from my Discord server who were essential for making this project progress and become what it is now.

External links

• GitHub - https://github.com/XorTroll/emuiibo
• Twitter - https://twitter.com/xortroll
• GBAtemp - https://gbatemp.net/threads/emuiibo-mitming-nfp-services-for-amiibo-emulation.536210/