diff --git a/README.md b/README.md index f875276..eea993e 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,83 @@ meshbox ======= -This is the OpenWRT package feed for the [meshbox][meshbox] project. It provides UCI and LuCI integration for [cjdns][cjdns]. Tested with OpenWRT Barrier Breaker (trunk). +This is the OpenWrt package feed for the [meshbox][meshbox] project. + +Use it to turn a OpenWrt device into a mesh networking device using cjdns. +It provides UCI and LuCI integration for [cjdns][cjdns]. + +Tested with OpenWrt Chaos Calmer (r42153). [meshbox]: http://fund.meshwith.me [cjdns]: https://github.com/cjdelisle/cjdns -Integration into the OpenWRT buildroot is simple. +###(Before we begin) + +If you are using Debian / Ubuntu, you may want to ensure that these packages are installed: + + libncurses5-dev gawk subversion git mercurial tftp + +--- + +#Integrating the package with OpenWrt + +## Clone OpenWrt + $ git clone git://git.openwrt.org/openwrt.git $ cd openwrt - $ cp feeds.conf.default feeds.conf + +## Add meshbox to the buildroot + +####Option 1: Add the meshbox git repository to the OpenWrt feeds list. + $ echo 'src-git meshbox git://github.com/seattlemeshnet/meshbox.git' >> feeds.conf + +####Option 2: Clone the meshbox repo and use your local copy. + + $ echo 'src-link meshbox /path/to/meshbox' >> feeds.conf + +## Update the feeds and install the package + +Whichever option you've chosen, you'll need to update your feeds: + $ ./scripts/feeds update $ ./scripts/feeds install luci-cjdns -Then configure your firmware image: enable the luci-cjdns module, in addition to your usual settings, such as target system and profile. As usual, you'll need to hit space twice to make it `[*]` rather than `[M]`. +#Building + +You'll need to know the chipset of the device for which you intend to build your OpenWrt with meshbox. + +You're going to use menuconfig to set a few settings for the build. + + (not as root!) $ make menuconfig + +Once menuconfig is open, you have two primary goals: + +####1. Apply your typical OpenWrt build settings, such as target system and profile. + +For help on this part, see the "Image Configuration" section of this document: http://wiki.openwrt.org/doc/howto/build + +####2. Enable the luci-dns module + + (using the menus in menuconfig) LuCI -> Collections -> [*] luci + LuCI -> Collections -> [*] luci-ssl (if you want ssl) LuCI -> Project Meshnet -> [*] luci-cjdns + Network -> Routing and Redirection ---> -*- cjdns + + (for your local language) + LuCI -> Tranlations ---> luci-i18n- + +(You'll need to hit space twice to make these `[*]` rather than `[M]`.) -Then save and close the configuration menu, and allow OpenWRT to resolve dependencies: + +##Almost there - final steps + +Save and close the configuration menu, and allow OpenWrt to resolve dependencies: $ make defconfig @@ -30,36 +85,82 @@ Then build: $ make -If you have a multicore processor, you can build faster using `-j`, however the OpenWRT build process is not highly parallelized so your milage may vary. +If you have a multicore processor, you can build faster using `-j`, however the OpenWrt build process is not highly parallelized so your milage may vary. In any case, it takes a good minute to compile, so you might want to cuddle up with the CJDNS whitepaper: https://github.com/cjdelisle/cjdns/blob/master/doc/Whitepaper.md - $ make -j 4 + $ make -j4 V=s 1>output.log 2>error.log + (Use four cores, log stdout and stderror to separate files) -To update: +# Flashing - $ ./scripts/feeds update +##Use a compiled binary to flash with OpenWrt + +If the build is successful you will have compiled firmware binaries in the following directory: + + bin// + + ie: `openwrt/bin/ar7xx/openwrt-ar71xx-generic-tl-wdr3500-v1-squashfs-factory.bin` + +On some AP's, you can use the OpenWrt firmware upgrade tool to flash the binary from a web interface (LuCi) +`http://192.168.1.1` +(Tested on: TP-Link WDR-3500 v1) -Development ------------ +# Advanced Topics (only tested on Barrier Breaker) -You can point the OpenWRT buildroot to a local meshbox clone by editing `/feeds.conf`: +## Flash using the flash.sh script: - src-link meshbox /path/to/meshbox +you can use the flash.sh script to flash your device via tftp. -If you want to use a local clone of cjdns itself as well, edit `/cjdns/Makefile`: +The script is located in `/scripts/flashing/flash.sh` + + Usage: ./flash.sh firmware vendor + +## Using a local copy of CJDNS to compile: + + +If you want to use a local clone of cjdns itself, edit `/cjdns/Makefile`: PKG_SOURCE_URL:=file:///path/to/cjdns PKG_SOURCE_PROTO:=git PKG_SOURCE_VERSION:=master -You can then build a fresh package, that you can copy to the device, and then install. You need to delete the last clone everytime. + *Make sure to commit your changes to cjdns before building the + package. The OpenWrt buildroot will clone the local cjdns into + the build directory, omitting uncommitted changes.* + + $ cd + $ git add && git commit -a -m "" + +Then continue with the "Building" section above. + +## Building an .ipkg for opkg install: + +Alternativly to flashing via tftp, you can integrate meshbox and cjdns into an +existing OpenWrt installation. + +Build a fresh package from the compiled firmware to copy and install via ssh. + + $ cd + +####You'll need to delete the last clone everytime you compile the .ipkg. + + $ rm dl/cjdns-* + +####Now, make the .ipkg. - rm dl/cjdns-* make package/cjdns/{clean,compile} V=s - scp bin//packages/cjdns-*.ipkg root@:/tmp/cjdns.ipkg + +This will write a number of chipset specific binaries to `/bin/` + +####Then, scp the package to your device. + + scp bin//packages/cjdns*.ipkg root@:/tmp/cjdns.ipkg + +####Finally, remotely install the .ipkg from the device. + ssh root@ 'opkg install /tmp/cjdns.ipkg' -Make sure to commit your changes to cjdns before building the package. The OpenWRT buildroot will clone the local cjdns into the build directory, omitting uncommitted changes. + TODO