This document is a quick-start guide on how to install braiins OS on your mining device using a Linux computer. There are two ways how to test and use braiins OS:
Boot from SD card with braiins OS image, effectively keeping the stock firmware in the built-in flash memory. In case you encounter any issues, you can simply boot the stock firmware from the internal memory. This is a safe way we suggest to start with.
Permanently reflash the stock firmware, effectively replacing the manufacturer’s firmware completely with braiins OS. In this method the only way how to go back to the default stock setup is to restore the manufacturer’s firmware from a backup that you create during install.
Due to aforementioned reasons, it is higly recommended to install braiins OS firmware only on devices with SD card slots.
You will need:
Note: Commands used in this manual are instructional. You might need to adjust file paths and names adequately.
Download the latest released firmware images + signatures from: https://feeds.braiins-os.org/
The table below outlines correspondence between firmware image archive and a particular hardware type.
|braiins-os-firmware_zynq-dm1-g9_*.tar.bz2||Dragon Mint T1 with G9 control board|
|braiins-os-firmware_zynq-dm1-g19_*.tar.bz2||Dragon Mint T1 with G19 control board|
You can check the downloaded file for its authenticity and integrity. The image signature can be verified by GPG:
gpg2 --search-keys firstname.lastname@example.org for i in ./braiins-os-firmware_*.tar.bz2; do gpg2 --verify $i.asc; done
You should see something like:
gpg: assuming signed data in './braiins-os-firmware_zynq-am1-s9_2018-09-22-0-853643de.tar.bz2' gpg: Signature made Sat 22 Sep 2018 02:27:03 PM CEST using RSA key ID 616D9548 gpg: Good signature from "Braiins Systems Release Key (Key used for signing software made by Braiins Systems) <email@example.com>" [ultimate]
Unpack the firmware image:
for i in ./braiins-os-firmware_*.tar.bz2; do tar xvjf $i; done
The downloaded firmware image contains SD card components as well has a transitional firmware that can be flashed into device’s on-board flash memory.
Insert an empty SD card into your reader and identify its block device (e.g. by
lsblk). You need an SD card with minimum capacity of 32 MB.
cd braiins-os-firmware_am1-s9-latest; sudo dd if=sd.img of=/dev/your-sd-card-block-device sync
If you know the MAC address of your device, mount the SD card and adjust the MAC address. in
uEnv.txt (most desktop Linux systems have automount capabilities once you reinsert the card into your reader). The
uEnv.txt is environment for the bootloader and resides in the first (FAT) partition of the SD card. That way, once the device boots with braiins OS, it would have the same IP address as it had with the factory firmware.
Once the SD card works, it is very safe to attempt flashing the built-in flash memory as there will always be a way to recover the factory firmware.
Follow the steps below. The tool creates a backup of the original firmware in the
backup folder. It is important to keep the backup safe to resolve any potential future issues.
Below are steps to replace original factory firmware with braiins OS. The tool attempts to login to the machine via SSH, therefore you maybe prompted for a password.
cd braiins-os-firmware_am1-s9-latest/factory-transition virtualenv --python=/usr/bin/python3 .env source .env/bin/activate pip install -r ./requirements.txt python3 upgrade2bos.py your-miner-hostname-or-ip
Restoring the original factory firmware requires issuing the command below. Please, note that the previously created backup needs to be available.
python3 restore2factory.py backup/backup-id-date/ your-miner-hostname-or-ip
If anything goes wrong and your device seems unbootable, you can use the previously created SD card image to recover it (flash the manufacturer’s firmware to the built-in flash memory):
cd braiins-os-firmware_am1-s9-latest/factory-transition python3 restore.py --sd-recovery backup/2ce9c4aab53c-2018-09-19/ your-miner-hostname-or-ip
After the script finishes, wait a few minutes and adjust jumper to boot from NAND (internal memory) afterwards.
Firmware upgrade process uses standard mechanism for installing/upgrading software packages within any OpenWrt based system. Follow the steps below to perform firmware upgrade:
# download latest packages from feeds server $ opkg update # try to upgrade to the latest firmware $ opkg install firmware
Since the firmware installation results in reboot, the following output is expected:
root@MINER:~# opkg install firmware Upgrading firmware on root from 2018-09-22-0-853643de to 2018-09-22-1-8d9b127d... Downloading https://feeds.braiins-os.org/am1-s9/firmware_2018-09-22-1-8d9b127d_arm_cortex-a9_neon.ipk Running system upgrade... --2018-09-22 14:23:47-- https://feeds.braiins-os.org/am1-s9/firmware_2018-09-22-1-8d9b127d_arm_cortex-a9_neon.tar Resolving feeds.braiins-os.org... 22.214.171.124, 126.96.36.199, 2400:cb00:2048:1::6819:6165, ... Connecting to feeds.braiins-os.org|188.8.131.52|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 10373471 (9.9M) [application/octet-stream] Saving to: '/tmp/sysupgrade.tar' /tmp/sysupgrade.tar 100%[==============================================================================>] 9.89M 10.7MB/s in 0.9s 2018-09-22 14:23:48 (10.7 MB/s) - '/tmp/sysupgrade.tar' saved [10373471/10373471] Collected errors: * opkg_conf_load: Could not lock /var/lock/opkg.lock: Resource temporarily unavailable. Saving config files... Connection to 10.33.0.166 closed by remote host. Connection to 10.33.0.166 closed.
Factory reset is as simple as uninstalling the the current firmware package:
$ opkg remove firmware
This effectively downgrades your firmware version to whatever it was when the transition to braiins OS has been done for the first time.