arm9launcher
Copyright 2016 Gabriel Marcano
This project is licensed under the GPL 2 or later licenses, at your choice. Refer to COPYING for more licensing information and for the licensing for the code borrowed from other sources.
This set of programs form a 3DS ARM9 payload selector, or bootloader. This project was started for two reasons: the author thought most ARM9 payload selectors in existence were too convoluted for their own good, and he wanted an application to showcase the usage of his general purpose libctr9 3DS ARM9 code library.
Currently arm9launcher supports the following:
-Button based payload selection, configurable via a configuration file
-Human readable configuration file, in JSON format
-Payloads can be launched from an external SD card, and internal CTRNAND, TWLN, and TWLP partitions
-The configuration and bootloader files can be stored in CTRNAND or an SD card.
Planned features:
-Menu based payload selection
--Author is open to suggestions
Note that this project is still under active development. Please
Autotools in general. These are used to create the build scripts.
https://github.com/gemarcano/libctr9 - Used for general 3DS ARM9 functionality. See that repository for instruction on how to install it.
Freetype2. Needed by libctr9.
The Autotools setup assumes that devkitarm is already in the PATH. It also assumes the environmental variable CTRARM9 is set to wherever the --prefix used to install libctr9 is.
export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin export CTRARM9=[root path of libctr9 installation] autoreconf -if ./configure --host arm-none-eabi --prefix=$CTRARM9 make
Example: export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin export CTRARM9=~/.local/usr/arm-none-eabi-9 autoreconf -if ./configure --host arm-none-eabi --prefix=$CTRARM9 make -j10
In the src/ directory after make is run, the files arm9loaderhax.bin and
arm9launcher.bin are the loader and bootloader, respectively. These can be
copied to the root of an SD card or the root of CTRNAND.
Besides the executables, the loader needs a configuration file, arm9launcher.cfg. An example configuration file is included on the root of the armlauncher repository. This configuration needs to be on the root of an SD card or CTRNAND.
The configuration file is in JSON. Every entry is in a key, value pair. The configuration JSON consists of a configuration entry with a value of an array of entries. Each configuration entry is a JSON object with some keys.
Each entry requires the following keys with values:
"name" : "a string representing a name of a payload (unused currently)"
"location : "path to the payload. Use SD:/, CTRNAND:/, TWLN:/, TWLP:/ prefixes for accessing payloads in the different partitions."
"buttons" : [ "array of strings representing which buttons trigger a particular choice. Multiple buttons for a single entry are supported."] Buttons supported include (case sensitive): "None" - Represents the payload chosen if no buttons are pressed "A" "B" "Select" "Start" "Right" "Left" "Up" "Down" "R" "L" "X" "Y" Note that this list does not include the second shoulder buttons found on the N3DS, nor the home menu button. Those are handled separately in the 3DS hardware than how the rest of the buttons are polled. This is something the author can look into addressing at some later date.
Entries support the following optional entries:
See the arm9launcher.cfg file included in the repository for an example configuration file.
When the arm9loaderhax.bin program is launched somehow, it will read the current HID input state (buttons) to determine which payload to load. It will then try to parse the configuration file it finds (either on the SD card or on the CTRNAND, in that order). If the HID state matched any of the payloads described in the configuration file, it will then try to hand off execution to the arm9launcher.bin to actually launch the payload.
If an error occurs, like the SD card being really screwed up, or NAND is bad, or the configuration file is bad, or if the payload was not found, some error will be reported. Pressing any button will cause the system to power off. Currently error messages are not exactly user friendly.
Please report these to the issue tracker at the repository, and these will be addressed as soon as possible, if not at least acknowledged. The more detailed the reports, the more likely they are to be addressed quickly. In particular, the following information can be quite useful when debugging bugs:
Pull requests are welcome. All requests will be looked at in detail, and must be documented in a similar fashion as the rest of the code for this project. In particular, it is unlikely (but not impossible) that code that emmits warnings with the warnings in use by this library would be merged without first fixing/ addressing what is causing the warnings to be emitted.