Differences

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

doc:howto:user.edittoh [2013/03/23 09:19]
jeq
doc:howto:user.edittoh [2013/04/25 17:44] (current)
xiloynaha use relative links where possible
Line 1: Line 1:
-**How to start (or advance) the process of getting OpenWRT support for a particular router**+====== How to start (or advance) the process of getting OpenWrt support for a particular router ======
-If router ABCD isnt 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 Table Of Hardware is the starting point - it lists many routers, but not all. Check if your router is in section 3 (Possible but not being worked on) or section 4 (Unsupportable).+  * 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 it lists many routers, but not all. Check if your router is in section 3 (//Possible but not being worked on//) or section 4 (//Unsupportable//)
 +  * If router ABCD is already listed in section 3 [[toh/start#possible.but.not.being.worked.on|TOH Possible but not being worked on]] then check the Wiki page for ABCD to see whether all of the desirable information is already present. Go to step 2 to see how. 
 +  * 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. A guide as to whether the router might be unsupportable is here [[toh/start#unsupportable|TOH Unsupportable]]. Available memory is an issue, with some devices having less that 16MB RAM. However note that in [[http://forum.openwrt.org/viewtopic.php?id=33908|Sept 2012]] the minimum RAM was stated to be 32MB.
-If router ABCD is already listed in section 3 [[toh/start#possible.but.not.being.worked.on|TOH Possible but not being worked on]] then check the Wiki page for ABCD to see whether all of the desirable information is already present. Go to step 2 to see how. 
-If there's no Wiki page, consider creating one.+===== Edit the Table of Hardware =====
-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. A guide as to whether the router might be unsupportable is here [[toh/start#unsupportable|TOH Unsupportable]]. Available memory is an issue, with some devices having less that 16MB RAM. However note that in [[http://forum.openwrt.org/viewtopic.php?id=33908| Sept 2012]] the minimum RAM was stated to be 32MB. 
- 
- 
-==== 1. Edit the Table of Hardware ==== 
To add a router to the TOH and create a Wiki page for it, follow these steps: To add a router to the TOH and create a Wiki page for it, follow these steps:
-- create a DokuWiki account for yourself (note: it's different to a forum account). Click on Register in the Actions block on any page. Now log in.+  - Create a DokuWiki 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.) 
 +  - 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.
-- browse to the device template, here : http://wiki.openwrt.org/meta/template_device 
-- open the template by clicking on 'Edit this page', click on the white editor window, then select all (Ctrl-A) and copy the contents to clipboard (Ctrl-C). Finally click cancel to exit +===== Check the present information =====
-  +
-(during the next three steps do not alter the clipboard contents.) +
- +
-- edit the relevant section of the TOH where you wish to create a new row for your router. Each section has its own edit button. +
-(examine existing rows in the table in order to to understand the syntax or, if unsure, try experimenting here :  http://wiki.openwrt.org/meta/playground ) +
-Avoid clicking on 'Edit this page' when editing just a section. When the row 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 +
- +
-- now paste the contents of the clipboard to the editor (Ctrl-V) and click on save +
- +
-- edit the new page again, this time in line with the advice provided within it. Note that this will probably take multiple edits over several days. +
- +
- +
-==== 2. Check the information is present ====+
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. 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.
Line 47: Line 34:
  * the precise flash layout   * the precise flash layout
-Some help with obtaining this information is provided here : +Some help with obtaining this information [[..devel/hw.hacking.first.steps|is provided]]. (From that page also click on add.new.device for further detail on the process of creating a new firmware.)
-http://wiki.openwrt.org/doc/devel/hw.hacking.first.steps+
-(From that page also click on add.new.device for further detail on the process of creating a new firmware.)+To add a photograph to the Wiki view these pages: 
 +  * [[meta/playground]] 
 +  * https://www.dokuwiki.org/images 
 +  * https://www.dokuwiki.org/media_manager 
 + 
 +One thing to check as soon as the CPU type is known, is whether support for the CPU (platform) has already been [[https://dev.openwrt.org/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.
-To add a photograph to the Wiki view these pages: 
-http://wiki.openwrt.org/meta/playground 
-https://www.dokuwiki.org/images 
-https://www.dokuwiki.org/media_manager 
-==== Further considerations ====+===== Further considerations =====
A few additional comments A few additional comments
Line 63: Line 51:
  * A router that's currently unsupported may very well require a connection to its serial console during development or testing   * 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.)+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. 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 +  * 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+  * 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. 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.+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.+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 [[doc/howto/buildroot.exigence|here]]. Some further comments about OpenWRT BuildRoot have been provided [[about/toolchain| here]].+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://forum.openwrt.org/viewtopic.php?id=8410)| here]]. Another tutorial discussing the same but written in 2013, with more detail is [[http://linksprite.com/wiki/index.php5?title=Tutorial_of_compiling_OpenWRT+How to set up an OpenWrt build environment on a Windows PC in a virtual machine is discussed [[http://forum.openwrt.org/viewtopic.php?id=8410)| here]]. Another tutorial discussing the same but written in 2013, with more detail is [[http://linksprite.com/wiki/index.php5?title=Tutorial_of_compiling_OpenWRT
|here]]. |here]].
-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 NNGB. Some articles suggest that a newcomer could build a custom OpenWRT firmware as a weekend project but this assumes that someone has provided device-specific instructions. +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.
-The final comment should be that flashing OpenWRT to a router without //router-specific instructions// (i.e. taken from the device Wiki page) contains an 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 real and significant.+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 :+The problems are most likely to derive from:
  * overwriting the bootloader   * overwriting the bootloader
  * including too many packages in the [[https://forum.openwrt.org/viewtopic.php?id=19281|custom firmware]]   * including too many packages in the [[https://forum.openwrt.org/viewtopic.php?id=19281|custom firmware]]
-  * Flashing using TFTP instead of WebGUI; or vice-versa +  * Flashing with wrong method e.g. TFTP instead of WebGUI; or vice-versa 
-  * forgetting to nnnn +  * code inserted into the bootloader by the manufacturer, designed to stop third-party firmware from running
-  * doing nnnn+
-The device-specific instructions in the Wiki give some reasons for bricking various routers. Some routers selected purely at random +If you **do** brick your router the problem can be made worse by
-  * [[toh/tp-link/tl-wr941nd|TL-WR941ND]] can be bricked in several ways+  * not having a backup of the bootloader and ART/NVRAM partitions 
 +  * shorting pins together as a way to unbrick the device
-[this section requires expert assistance, please ;-) ]+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]].

Back to top

doc/howto/user.edittoh.1364026775.txt.bz2 · Last modified: 2013/03/23 09:19 by jeq