The word "brick", when used in reference to consumer electronics, describes an electronic device such as a smart phone, game console, router, or tablet computer that, due to a serious misconfiguration, corrupted firmware, or a hardware problem, can no longer function, hence, is as useful as a "brick".
There are three levels of damage that can be caused by the user to Black Swift board without physically damaging it:
- Damaged configuration: mistakes were made in some configuration files, so the board is unable to boot properly or inaccessible via its network interfaces. To fix the problem, one needs to reset the board to its factory state using Reset button or fix the files via serial console.
- Damaged OpenWRT image: inappropriate OS image was flashed (for example, user-prepared image with some configuration mistakes or image made for another hardware). In this case you need to reflash an image using bootloader's serial console.
- Damaged bootloader: bootloader was damaged beyond repair (as a result of mistakes during bootloader's serial console operations or other attempts to directly access flash memory). The only way to restore the board is to reprogram NOR flash chip using external programmer.
Please note that 999 out of 1000 users will never end with damaged bootloader, and 99 out of 100 — with damaged OpenWRT image. In most cases, damage is caused by accidental mistakes in configuration files or failures in software packages installed by user — these problems can be easily fixed with Reset button or serial console access.
Factory reset button
There's a factory reset button placed in the corner of the Black Swift's PCB. By pressing it for 10 seconds or longer you will undo all settings you made, including software packages you installed, and reset the board to factory default. For example, if you entered wrong Wi-Fi password and so you're unable to connect to the board anymore, pressing Reset button for 10 seconds will revert the board to default AP mode with unencrypted Black Swift Wi-Fi network.
As for now, the button is supported on OS level, not bootloader, by the hotplug daemon — so in fact it is possible to change OpenWRT's setting in such a way that button would not work. Special bootloader recovery mode will be added later.
Recovery from USB-flash drive
Modified for the Black Swift version of the popular bootloader U-Boot supports several modes of firmware recovery, including - the restoration of individual sections or the entire amount of flash memory card with a USB-flash drive.
Preparing the USB drive:
- Format the memory card in the FAT or FAT32 file system
- Create a _BSB folder on it and put one of the following files:
- autorun: script with console commands U-Boot.
- u-boot.bin: u-boot partition image (U-boot itself, 128 KB size).
- u-boot-env.bin: u-boot-env image of partition (U-Boot environment variables, size 64 KB).
- firmware.bin: the image of the OpenWRT partition (the size may be different).
- art.bin: image of the ART section (size 64 KB).
- dump.bin: full flash image (16 MB size).
- Turn off the power of the Black Swift
- Connect the USB-stick to the connector «Host» of the board
- Press and hold the "Reset" button
- Turn on the Black Swift
- After the LED on the board flashes once, release the Reset button
On the successful upgrade of the firmware, the board signals 5 flashes of the LED, about a failure in the process of updating - with 20 quick flashes.
In addition, the Reset button can be used to enter other recovery modes:
- Mode 0: press <2 seconds or >10 seconds: start OpenWRT with CPU and memory settings by default
- Mode 1: 2...4 s: firmware upgrade from USB stick
- Mode 2: 4...6 s: login to the console U-Boot
- Mode 3: 6...8 s: launch of the built-in U-Boot web server
- Mode 4: 8...10 s: launching the U-Boot network console
The selected mode is indicated by LED flashes: for example, if you need a web server, wait until the LED flashes three times in a row, and release the Reset button.
Restoring individual files with serial console
Serial console is a very powerful tool that gives you access to bootloader as well as OpenWRT even if the board is not accessible via Wi-Fi or Ethernet (for example, if you altered its network settings and made some mistake).
Black Swift PRO has an integrated Serial-USB converter, so to access it, all you need is regular microUSB cable — plug it in board's power microUSB connector and in your PC's USB port.
Black Swift Basic has serial port as well, but no onboard Serial-USB converter, so you need to use external one. Any Serial adapter with 3.3V logic level will do (e.g. this one from Adafruit); do not use 5V Serial adapters — Black Swift is not 5V-tolerant. Connect adapter's TX pin to Black Swift's RX pin (using 1.27→2.54 mm adapter or some other way), RX to TX, GND to GND. Black Swift can be powered by connecting 5V pin of the adapter to 5V pin of the board or with regular microUSB power supply. Plug adapter into your PC and wait for the driver to install.
To access serial console you need software called "serial terminal emulator" — we recommend ExtraPuTTY, an excellent fork of well-known PuTTY SSH client. Download, install and run it.
Click «Serial» section (in the menu on the left) and set settings as shown below:
Serial line (COM port) number in your case can be different, but it's easy to find — ExtraPuTTY shows you active ports only, usually you'll find there COM1 and some other port, and the latter is what you need. Baud rate should be 115200, data bits = 8, stop bits = 1, no parity, no flow control.
Switch back to «Session» and choose «Serial» mode. Click «Open».
Terminal window will open. Now connect the power to the Black Swift (or reset it) — and you will see the board booting:
Do not press anything until booting is completed (it tooks around 35 seconds). After that hit Enter and you will be presented with Linux console:
Here you can use regular Linux command-line tools. Let's have a look on a simple example — correcting Wi-Fi settings. Let's assume you messed something in /etc/config/wireless file, where SSID and password are stored, so your board is not accessible via Wi-Fi anymore.
Fortunately, due to OpenWRT's two-layer filesystem structure there's always a backup. First layer is the squashfs filesystem — preloaded OpenWRT image which can not be changed except when reflashing it with sysupgrade command. Second layer is jffs2 overlay filesystem — it is where all the files you've changed are stored. With the new board, there's only one copy of /etc/config/wireless file — in the squashfs filesystem; but if you change a single character in it, a copy will be created and stored in the overlay filesystem. When system has 2 copies of the file, one that resides in overlay is considered active.
To revert wireless settings back to factory defaults (stored in squashfs filesystem) you need to simply delete your own /etc/config/wireless file (stored in overlay filesystem) and reboot:
rm -f /etc/config/wireless reboot
If you want to change something in the file, invoke nano text editor:
When you've done, press Ctrl-X to exit nano. You will be asked to save the file: press "Y" for "Yes", "N" for "No" or "C" to get back to nano.
Another common example is changing root password — if you forgot the one you set before:
If you want to revert all board's setting to factory defaults, run the following command:
It is an equivalent of pressing Reset button for 10 seconds.
Reflashing firmware with serial consoleNB: Bootloader command-line interface let you play with the flash memory without limitations, including the section where bootloader itself is placed. Double check every address you are entering. There's no any kind of protection against errors, so if you accidentally destroy bootloader — there would be no way to unbrick the board except reflashing the NOR chip with external programmer.
In a rare case when OpenWRT was damaged beyond repair (for example, if you tried to upgrade it using broken image), serial console is needed to upload the new firmware image.
Connect the board to your PC through serial link (as described above)
- Launch ExtraPuTTY and set up connection
- Prepare to hit any key on PC's keyboard and power the board
- As soon as "Hit any key to stop autobooting" appears — hit any key
- If you missed the moment — restart the board by disconnecting its power and try again
You are in bootloader's serial console now. Next step is to upload new firmware image via YModem protocol. Type "loady" and hit Enter:
Select "File Transfer" — "Y modem" — "Send" in PuTTY's menu, and choose the image *.bin file. Transfer will begin automatically:
As soon as transfer is completed (it takes up to 30 minutes, depending on image size), image will be stored in board's RAM. Please note RAM address (0x80800000) and image size (0x01000000 in this particular case, but in your case it can be different!):
On the next step you need to erase flash memory section where you want to put new image:
erase start +size
Адрес стираемой секции (start) зависит от того, что именно вы планируете перепрошить. Образ OpenWRT начинается с адреса 0x9f030000, другие секции описаны в статье Структура флэш-памяти. В данном конкретном примере мы перепрошиваем всю флэш-память целиком, поэтому начальный адрес — 0x9F000000. Size — это размер образа, который был показан командой loady после его загрузки (в данном случае это 0x01000000 — но у вас размер будет другим!).
Hit Enter and wait a bit. After erasing is completed, copy the new image from RAM (0x80800000) to flash with the cp.b command:
cp.b from to size
Where from is the RAM address (0x80800000), to is the flash address (0x9F000000 in this particular example) and size is the image size. Note that there's no "+" sign before size in cp.b parameters.
And now you are ready to restart the board with reset command.NB: Bootloader command-line interface let you play with the flash memory without limitations, including the section where bootloader itself is placed. There's no any kind of protection against errors, so if you accidentally destroy bootloader — there would be no way to unbrick the board except reflashing the NOR chip with external programmer. If you misspelled something in erase or cp.b command — do not panic, but run it again with proper parameters, as you still have firmware image stored in RAM until you reboot the board.