User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:howto:user.edittoh [2013/04/18 23:41]
doc:howto:user.edittoh [2017/01/17 21:30] (current)
tmomas This page contains outdated information and needs a complete overhaul.
Line 1: Line 1:
 +FIXME //Outdated information all over the page. Needs a complete overhaul.// ​ --- //tmomas 2017/01/17 21:25//
 +====== How to start (or advance) the process of getting OpenWrt support for a particular router ======
 +  * If router ABCD isn't already supported by OpenWrt and it isn't a work-in-progress either, then it might be possible to help get the work started. The [[toh/​start|Table of Hardware]] is the starting point. Check if your router is already supported or not.
 +  * If router ABCD is not listed as supported, or not listed at all, then search the wiki for ABCD to see whether all of the desirable information is already present.
 +  * If there'​s no Wiki page, consider creating one.
 +  * If it's not known whether the router can run third-party firmware, you may need to start by assuming that OpenWrt support is at least possible. Available memory is an issue, with some devices having less than 16MB RAM. However note that in [[http://​​viewtopic.php?​id=33908|Sept 2012]] the minimum RAM was stated to be 32MB.
 +===== Edit the Table of Hardware =====
 +To add a router to the TOH and create a Wiki page for it, follow these steps:
 +  - Create a wiki account for yourself (note: it's different to a forum account). Click on Login in the Actions block on any page, then click on Register… Now log in. (It's easiest to keep this page visible during the following steps and open two new browser tabs along the way.)
 +  - <​del>​Browse (in new tab) to the relevant manufacturer section of the TOH where you wish to create a new row for your router. For example, you may wish to add the router to section 3, [[toh/​start#​possible.but.not.being.worked.on|TOH Possible but not being worked on]]. Click on edit for the relevant section (note that each section has its own edit button). A particular syntax is used so examine existing rows in the table in order to to understand what to do or, if unsure, try [[meta/​playground|experimenting]] beforehand. Avoid clicking on //Edit this page// when you only need to edit one section. When the row for your router has been created click on save.
 +  - Once saved, the new row for router ABCD should become visible. Now click on the link that's been automatically created in the first column.
 +  - The wiki page “behind” the link won't exist yet so, when advised of this, click on '​create this page ' in the Actions block. This creates the page and opens the editor, ready for the new content.
 +  - Browse (in new tab) to the [[meta/​template_device|device template]].
 +  - Open the template by clicking on //Edit this page//, click on the white editor window, then select all of the text (Ctrl-A) and copy the contents to clipboard (Ctrl-C). Finally click //Cancel// to exit without making changes. (During the next three steps do not alter the clipboard contents.)
 +  - Go back to the Wiki page that you just created and is being edited in the other tab. Paste the contents of the clipboard to the editor (Ctrl-V) and then click on save.
 +  - Now edit the new page again, this time in line with the advice provided within it. Note that this will probably take multiple edits as information becomes available.</​del>​ completely outdated ​ --- //tmomas 2017/01/17 21:10//
 +===== Check the present information =====
 +Certain information on router ABCD needs to be collected before it can be worked on. The device template has been created so that all of this information (and more) can be recorded in a consistent fashion.
 +The desirable information includes
 +  * the type of CPU
 +  * available GNU/Linux drivers for that hardware
 +  * the type of Flash memory chip
 +  * quality photograph of the PCB
 +  * OEM boot log
 +  * the type of bootloader
 +  * the precise flash layout
 +  * [[meta:​adding_images_to_openwrt_wiki|Add images of the PCB]]
 +Some help with obtaining this information [[..devel/​hw.hacking.first.steps|is provided]]. (From that page also click on for further detail on the process of creating a new firmware.)
 +One thing to check as soon as the CPU type is known, is whether support for the CPU (platform) has already been [[https://​​wiki/​platforms|added to OpenWrt]].
 +Adding support for a platform is documented on the OpenWrt site but the process is significantly longer than adding support for a specific router whose CPU is already supported.
 +===== Further considerations =====
 +A few additional comments
 +  * In order to obtain the OEM boot log and precise flash layout it's likely that a connection to the router'​s serial console will need to be set up. This will probably require soldering to be done.
 +  * A router that's currently unsupported may very well require a connection to its serial console during development or testing
 +Note that opening up the router and soldering wires to the serial console will both void the manufacturer'​s warranty. If this is contrary to your needs then you will need to rely on others to get router ABCD supported in the OpenWrt project. (But bear in mind that if the task is not sufficiently interesting it's less likely that others will get involved.)
 +In the device template there'​s a link to a Wiki page which discusses how to set up a link from a PC to the serial console of a router.
 +  * Creating OpenWrt firmware for router ABCD will require the OpenWrt code to be compiled specifically for that device, in a Linux environment
 +  * At some stage someone will need to flash the OpenWrt firmware onto router ABCD for the first time
 +Both of the above place requirements on the owner of the router. Some knowledge needs to be acquired.
 +It sometimes happens that an OpenWrt developer will take an interest in router ABCD but this cannot be guaranteed. If they happen to have access to router ABCD that makes things easier, so hardware donations can definitely help.
 +The only way that an owner of router ABCD can //​guarantee//​ that an attempt to produce an OpenWrt firmware will be made is if they undertake that work.
 +A guide to understanding what an OpenWrt development environment consists of is provided [[.buildroot.exigence|here]]. Some further comments about OpenWrt BuildRoot have been provided [[about/​toolchain| here]].
 +How to set up an OpenWrt build environment on a Windows PC in a virtual machine is discussed [[http://​​viewtopic.php?​id=8410)| here]]. Another tutorial discussing the same but written in 2013, with more detail is [[http://​​wiki/​index.php5?​title=Tutorial_of_compiling_OpenWRT
 +A PC that's used to produce OpenWrt firmware will need up to 2GB of free disk space and that's just for the OpenWrt code (a stable branch). The total requirement could be 4GB. Some articles suggest that a newcomer could build a custom OpenWrt firmware as a weekend project but this assumes that someone else has already provided device-specific instructions. ​
 +Flashing OpenWrt to a router without //​device-specific instructions//​ (i.e. taken from the device wiki page) contains a significant element of risk. For example, some (many) routers have to be flashed with a specific version of OpenWrt, otherwise you end up with a brick. The chances of bricking your router when you flash it the first time are very real.
 +The problems are most likely to derive from:
 +  * overwriting the bootloader
 +  * including too many packages in the [[https://​​viewtopic.php?​id=19281|custom firmware]]
 +  * Flashing with wrong method e.g. TFTP instead of WebGUI; or vice-versa
 +  * code inserted into the bootloader by the manufacturer,​ designed to stop third-party firmware from running
 +If you **do** brick your router the problem can be made worse by:
 +  * not having a backup of the bootloader and ART/NVRAM partitions
 +  * shorting pins together as a way to unbrick the device
 +The device-specific instructions in the Wiki give some reasons for bricking various routers; see for example the [[toh/​tp-link/​tl-wr941nd|TL-WR941ND]],​ that can be bricked in several ways. A dedicated page helps you [[doc/​howto/​generic.debrick|debricking your router]].