installation.adoc (7509B)
1 = Installation 2 3 Hardware devices vary wildly in their affordances for installing new 4 operating systems, so it should be no surprise that the Liminix 5 installation procedure is hardware-dependent. This section contains 6 generic instructions, but please refer to the documentation for your 7 device to find whether and how well they apply. 8 9 Most of the supported devices fall into one of two broad categories: 10 11 * devices we install by preparing a raw flash image and copying it 12 directly onto (some part of) the flash. This is analogous to (though 13 not quite the same as) using 14 https://www.man7.org/linux/man-pages/man1/dd.1.html:dd(1) on a 15 "grown up" computer to copy a raw disk image. Devices in this 16 category are usually smaller, older, and/or less powerful. 17 18 * devices where the vendor provides a "higher level" storage 19 abstraction, such as http://linux-mtd.infradead.org/doc/ubi.html:UBI 20 over raw flash, or a consumer flash such as MMC, or another storage 21 technology entirely. Installation on these devices is less uniform 22 because it depends on exactly what kind of storage abstraction. 23 24 25 == Building a firmware image 26 27 Liminix uses the Nix language to provide congruent configuration 28 management. This means that to change anything about the way in which a 29 Liminix system works, you make that change in your `+configuration.nix+` 30 (or one of the other files it references), and rerun `+nix-build+` to 31 action the change. It is not possible (at least, without shenanigans) to 32 make changes by logging into the device and running imperative commands 33 whose effects may later be overridden: `+configuration.nix+` always 34 describes the entire system and can be used to recreate that system at 35 any time. You can usefully keep it under version control. 36 37 If you are familiar with NixOS, you will notice some similarities 38 between NixOS and Liminix configuration, and also some differences. 39 Sometimes the differences are due to the resource-constrained devices we 40 deploy onto, sometimes due to differences in the uses these devices are 41 put to. 42 43 For a more full description of how to configure Liminix, see 44 <<_configuration>>. Assuming for the moment that you want a typical home 45 wireless gateway/router, the best way to get started is to copy 46 `+examples/rotuer.nix+` and edit it for your requirements. 47 48 [source,console] 49 ---- 50 $ cp examples/rotuer.nix configuration.nix 51 $ vi configuration.nix # other editors are available 52 $ # adjust this next command for your hardware device 53 $ nix-build -I liminix-config=./configuration.nix \ 54 --arg device "import ./devices/gl-mt300a" -A outputs.default 55 ---- 56 57 For raw flash devices, this will leave you with a file 58 `+result/firmware.bin+` which you now need to write to the flash. 59 For other devices, _please check the device documentation_ 60 61 == Flashing from the boot monitor (TFTP install) 62 63 You will need 64 65 * to open the device and attach a TTL serial adaptor of some kind 66 * a TFTP server on the network that the device is plugged into 67 (or can be plugged into for installation) 68 69 Installing via serial connection is quite hardware-specific and 70 depending on the device may even involve soldering. However, it is in 71 some ways the most "reliable" option: if you can see what's happening 72 (or not happening) in early boot, the risk of "bricking" is 73 substantially reduced and you have options for recovering if you 74 misstep or flash a bad image. 75 76 [[serial]] 77 === Serial connections 78 79 To speak to U-Boot on your device you'll usually need a serial 80 connection to it. This typically involves opening the box, locating the 81 serial header pins (TX, RX and GND) and connecting a USB TTL converter 82 to them. 83 84 The Rolls Royce of USB/UART cables is the 85 https://cpc.farnell.com/ftdi/ttl-232r-rpi/cable-debug-ttl-232-usb-rpi/dp/SC12825?st=usb%20to%20uart%20cable[FTDI 86 cable], but there are cheaper alternatives based on the PL2303 and 87 CP2102 chipsets - or you could even get creative and use the 88 https://pinout.xyz/[UART GPIO pins] on a Raspberry Pi. Whatever you do, 89 make sure that the voltages are compatible: if your device is 3.3V (this 90 is typical but not universal), you don't want to be sending it 5v or 91 (even worse) 12v. 92 93 Run a terminal emulator such as Minicom on the computer at other end of 94 the link. 115200 8N1 is the typical speed. 95 96 [NOTE] 97 ==== 98 TTL serial connections often have no flow control and so don't always 99 like having massive chunks of text pasted into them - and U-Boot may 100 drop characters while it's busy. So don't do that. 101 102 If using Minicom, you may find it helps to bring up the "Termimal 103 settings" dialog (C^A T), then configure "Newline tx delay" to some 104 small but non-zero value. 105 ==== 106 107 When you turn the router on you should be greeted with some messages 108 from U-Boot, followed by the instruction to hit some key to stop 109 autoboot. Do this and you will get to the prompt. If you didn't see 110 anything, the strong likelihood is that TX and RX are the wrong way 111 around, or your computer is expecting flow control which the 3 wire 112 connection does not provide. If you see garbage, try a different 113 speed. 114 115 Interesting commands to try first in U-Boot are `+help+` and 116 `+printenv+`. 117 118 === TFTP 119 120 You will also need to configure a TFTP server on a network that's 121 accessible to the device: how you do that will vary according to which 122 TFTP server you're using and so is out of scope for this document. 123 124 HINT: <<tufted>>, a rudimentary TFTP server, is supplied with Liminix 125 for development purposes. It may or may not fit your needs here. 126 127 ==== Building and installing the image 128 129 Follow the device-specific instructions for "TFTP install": usually, the 130 steps are 131 132 * build the [.title-ref]#outputs.mtdimage# output 133 * copy `+result/firmware.bin+` to wherever your TFTP server serves files 134 from 135 * execute the commands listed in `+result/flash.scr+` at the 136 U-Boot command line 137 * reset the device 138 139 You should now see messages from U-Boot, then from the Linux kernel and 140 eventually a shell prompt. 141 142 NOTE: Before you reboot, check which networks the device is plugged into, and 143 disconnect as necessary. If you've just installed a DHCP server or 144 anything else that responds to broadcasts, you may not want it to do 145 that on the network that you temporarily connected it to for installing 146 it. 147 148 == Flashing from OpenWrt 149 150 CAUTION: Untested! A previous version of these instructions (without 151 the -e flag) led to soft-bricking the device when flashing a JFFS2 152 image. The current version _should_ work better but if you are reading this 153 message then nobody has yet confirmed it 154 155 If your device is running OpenWrt then it probably has the `+mtd+` 156 command installed. Transfer `+result/firmware.bin+` onto the running 157 device using e.g. `+scp+`. Now flash as follows: 158 159 [source,console] 160 ---- 161 mtd -e -r write /tmp/firmware.bin firmware 162 ---- 163 164 The options to this command are for "erase before writing" and "reboot 165 after writing". 166 167 For more information, please see the 168 https://openwrt.org/docs/guide-user/installation/sysupgrade.cli[OpenWrt 169 manual] which may also contain (hardware-dependent) instructions on how 170 to flash an image using the vendor firmware - perhaps even from a web 171 interface. 172 173 == Flashing from Liminix 174 175 If the device is already running Liminix then in general you cannot safely 176 copy a new image over the top of the running system while it is running. 177 178 If the running system was configured with <<levitate>> you can use 179 that to safely flash your new image. Otherwise you may attempt to use 180 `+flashcp+` directly, but bust out the serial leads in preparation for 181 it going horribly wrong. 182