mirror of https://github.com/aredn/aredn.git
418 lines
16 KiB
Markdown
418 lines
16 KiB
Markdown
# Amateur Radio Emergency Data Network AREDN(tm) Firmware
|
|
|
|
http://www.arednmesh.org
|
|
|
|
## About AREDN
|
|
|
|
AREDN wireless networks are deployed by licensed Amateur Radio
|
|
operators, Technician Class or higher, under FCC Part 97 allocations
|
|
adjacent to FCC part 15, unlicensed, WIFI, allocations. They are
|
|
configured as ad-hoc nodes to form mesh networks. The firmware
|
|
created below enables the effective use of valuable and dedicated
|
|
frequencies for communication services to government and private
|
|
relief organizations in times of disaster or other emergencies.
|
|
|
|
Amateur Radio frequencies are relatively clean of noise from the commercial
|
|
allocations and ensure usability for Amateur Radio Operators. This firmware
|
|
enables 802.11n wireless networks to be created and expanded with minimal
|
|
to no pre-planning or IT expertise. A user can deploy a 'node' anywhere
|
|
to connect in and extend an AREDN network. Device hardware options exist to
|
|
provide sector coverage, build point-to-point links, and connect end
|
|
point services to the network. High speed link rates are routinely achieved
|
|
over long distances, e.g. 60Mbps+ on 10MHz channels over 80km links.
|
|
|
|
For further information on obtaining an Amateur Radio Technician Class
|
|
license, please refer to http://www.arrl.org/getting-your-technician-license
|
|
|
|
## Usage Information
|
|
|
|
### What to know about the images built with the instructions below
|
|
|
|
This is the active 'main' branch with latest AREDN code.
|
|
At anytime a new change may be broken or break prior capabilities.
|
|
|
|
The Amateur Radio community is encouraged to participate in loading the
|
|
images produced from a "nightly build" and run the AREDN firmware in a
|
|
variety of environments. Given new features may not yet be documented,
|
|
participants should already have a basic knowledge of Linux and Networking to
|
|
understand and provide useful feedback to the Developer submitting the
|
|
code.
|
|
|
|
The goal of participation is to obtain confidence that new
|
|
features and the overall mesh node is stable. The more participation,
|
|
the earlier an issue is found, the faster an enhancement will be
|
|
turned into a release.
|
|
|
|
Please refer to https://github.com/aredn/aredn/issues
|
|
for a list of outstanding defects.
|
|
|
|
### Images built
|
|
|
|
Device | Target | Image | RAM | Stability
|
|
------ | ------ | ----- | --- | ---------
|
|
AirGrid XM | ath79 | ubnt_bullet-m-ar7241 | 32MB | untested sunset
|
|
AirGrid XW | ath79 | ubnt_bullet-m-xw | 32MB | untested sunset
|
|
AirRouter | ath79 | ubnt_airrouter | 32MB | untested sunset
|
|
AirRouter HP | ath79 | ubnt_airrouter | 32MB | untested sunset
|
|
Bullet M2Ti/M5/M5Ti | ath79 | - | 32MB | untested sunset
|
|
Bullet M2 | ath79 | ubnt_bullet-m-ar7241 | 32MB | stable sunset
|
|
Bullet M2 XW | ath79 | ubnt_bullet-m-xw | 64MB | untested
|
|
LiteBeam AC5 Gen2 | ath79 | ubnt_litebeam-ac-gen2 | 64MB | stable new
|
|
LiteBeam M5 | ath79 | - | 64MB | untested
|
|
NanoBeam AC 5 | ath79 | ubnt_nanobeam-ac | 64MB | untested new
|
|
NanoBeam AC 5 Gen 2 | ath79 | ubnt_nanobeam-ac-gen2 | 128MB | stable new
|
|
NanoBeam M2-13/M5-16/M5-19 | ath79 | - | 32MB | untested sunset
|
|
NanoBridge 2G18 | ath79 | ubnt_nanobridge-m | 32MB | untested sunset
|
|
NanoBridge 5G22/25 | ath79 | ubnt_nanobridge-m | 32MB | untested sunset
|
|
NanoBridge M9 | ath79 | ubnt_nanobridge-m | 32MB | untested sunset
|
|
NanoStation AC 5 | ath79 | ubnt_nanostation-ac | 64MB | stable new
|
|
NanoStation Loco M2/M5/M9 XM | ath79 | ubnt_nanostation-loco-m | 32MB | untested sunset
|
|
NanoStation Loco M2 XW | ath79 | ubnt_nanostation-loco-m-xw | 64MB | untested
|
|
NanoStation Loco M5 XW | ath79 | ubnt_nanostation-loco-m-xw | 64MB | stable
|
|
NanoStation M2/M3/M5 XM | ath79 | ubnt_nanostation-m | 32MB | stable sunset
|
|
NanoStation M2/M5 XW | ath79 | ubnt_nanostation-m-xw | 64MB | stable
|
|
PicoStation M2 | ath79 | ubnt_picostation-m | 32MB | untested sunset
|
|
PowerBeam AC 5 500 | ath79 | ubnt_powerbeam-5ac-500 | 128MB | stable new
|
|
PowerBeam-M2-400 | ath79 | ubnt_powerbeam-m2-xw | 64MB | untested
|
|
PowerBeam-M5-300 | ath79 | ubnt_powerbeam-m5-300 | 64MB | stable
|
|
PowerBeam-M5-400/400ISO/620 | ath79 | ubnt_powerbeam-m5-xw | 64MB | stable
|
|
PowerBridge | ath79 | ubnt_powerbridge-m | 64MB | untested
|
|
Rocket AC Lite 5 | ath79 | ubnt_rocket-5ac-lite | 128MB | stable new
|
|
Rocket M9/M2/M3/M5/M5GPS XM | ath79 | ubnt_rocket-m | 64MB | stable
|
|
Rocket M2/M5 XM with USB port | ath79 | ubnt_rocket-m | 64MB | untested
|
|
Rocket M2 XW | ath79 | ubnt_rocket-m-xw | 64MB | untested
|
|
Rocket M5 XW | ath79 | ubnt_rocket-m-xw | 64MB | stable
|
|
Rocket M2 Titanium TI | ath79 | - | 64MB | untested
|
|
Rocket M2 Titanium XW | ath79 | ubnt_rocket-m-xw | 64MB | untested
|
|
Rocket M5 Titanium TI | ath79 | - | 64MB | untested
|
|
Rocket M5 Titanium XW | ath79 | ubnt_rocket-m-xw | 64MB | stable
|
|
TPLink CPE210 v1.X | ath79 | tplink_cpe210-v1 | 64MB | stable
|
|
TPLink CPE210 v2.0 | ath79 | tplink_cpe210-v2 | 64MB | stable
|
|
TPLink CPE210 v3.0 | ath79 | tplink_cpe210-v3 | 64MB | untested
|
|
TPLink CPE220 v2.0 | ath79 | tplink_cpe220-v2 | 64MB | untested
|
|
TPLink CPE220 v3.0 | ath79 | tplink_cpe220-v3 | 64MB | untested
|
|
TPLink CPE510 v1.X | ath79 | tplink_cpe510-v1 | 64MB | untested
|
|
TPLink CPE510 v2.0 | ath79 | tplink_cpe510-v2 | 64MB | stable
|
|
TPLink CPE510 v3.0 | ath79 | tplink_cpe510-v3 | 64MB | stable
|
|
TPLink CPE605 v1.0 | ath79 | tplink_cpe605-v1 | 64MB | untested
|
|
TPLink CPE610 v1.0 | ath79 | tplink_cpe610-v1 | 64MB | untested
|
|
TPLink CPE610 v2.0 | ath79 | tplink_cpe610-v2 | 64MB | untested
|
|
TPLink CPE710 v1.0 | ath79 | tplink_cpe710-v1 | 128MB | stable new
|
|
TPLink WBS210 v1.0 | ath79 | tplink_wbs210-v1 | 64MB | untested
|
|
TPLink WBS210 v2.0 | ath79 | tplink_wbs210-v2 | 64MB | untested
|
|
TPLink WBS510 v1.0 | ath79 | tplink_wbs510-v1 | 64MB | untested
|
|
TPLink WBS510 v2.0 | ath79 | tplink_wbs510-v2 | 64MB | untested
|
|
Mikrotik Basebox RB912UAG-2HPnD | ath79 | mikrotik_routerboard-912uag-2hpnd | 64MB | untested
|
|
Mikrotik Basebox RB912UAG-5HPnD | ath79 | - | 64MB | untested
|
|
Mikrotik hAP ac lite 952Ui-5ac2nD | ath79 | mikrotik_routerboard-952ui-5ac2nd | 64MB | stable
|
|
Mikrotik RBLHG-2nD(-XL) | ath79 | mikrotik_routerboard-lhg-2nd | 64MB | stable
|
|
Mikrotik RBLHG-5nD | ath79 | mikrotik_routerboard-lhg-5nd | 64MB | stable
|
|
Mikrotik RBLHG-5HPnD(-XL) | ath79 | mikrotik_routerboard-lhg-5nd | 64MB | stable
|
|
MikroTik RBLHGG-5acD(-XL) | ipq40xx | mikrotik_lhgg-5acd | 256MB | stable new
|
|
Mikrotik RBLDF-2nD | ath79 | - | 64MB | untested
|
|
Mikrotik RBLDF-5nD | ath79 | - | 64MB | untested
|
|
Mikrotik QRT5 RB911G-5HPnD-QRT | ath79 | - | 64MB | untested
|
|
Mikrotik mANTBox RB911G-2HPnD | ath79 | - | 64MB | untested
|
|
Mikrotik mANTBox RB911G-5HPnD | ath79 | - | 64MB | untested
|
|
Mikrotik mANTBox RB912UAG-2HPnD | ath79 | mikrotik_routerboard-912uag-2hpnd | 128MB | untested
|
|
Mikrotik mANTBox RB912UAG-5HPnD | ath79 | mikrotik_routerboard-912uag-5hpnd | 128MB | stable
|
|
Mikrotik mANTBox RB921GS-5HPacD 15s | ath79 | mikrotik_routerboard-921gs-5hpacd-15s | 128MB | stable new
|
|
Mikrotik mANTBox RB921GS-5HPacD 19s | ath79 | mikrotik_routerboard-921gs-5hpacd-19s | 128MB | stable new
|
|
Mikrotik SXTsq 5HPnD | ath79 | mikrotik_routerboard-sxt-5nd | 64MB | stable
|
|
Mikrotik SXTsq 5nD | ath79 | mikrotik_routerboard-sxt-5nd | 64MB | stable
|
|
Mikrotik SXTsq 2nD | ath79 | - | 64MB | untested
|
|
MikroTik RouterBOARD D52G-5HacD2HnD | ipq40xx | mikrotik_hap-ac2 | 128MB | stable new
|
|
MikroTik RouterBOARD D53iG-5HacD2HnD | ipq40xx | mikrotik_hap-ac3 | 256MB | stable new
|
|
MikroTik RouterBOARD SXTsqG-5acD | ipq40xx | mikrotik_sxtsq-5-ac | 256MB | stable new
|
|
GL.iNet GL-AR150 | ath79 | glinet_gl-ar150 | 64MB | stable
|
|
GL.iNet GL-USB150 | ath79 | glinet_gl-usb150 | 64MB | stable
|
|
GL.iNet GL-AR300M16 | ath79 | glinet_gl-ar300m | 64MB | stable
|
|
GL.iNet GL-AR300M w/ 128MB NAND | ath79 | - | 64MB | untested
|
|
GL.iNet GL-AR750 | ath79 | glinet_gl-ar750 | 128MB | stable
|
|
Meraki MR-16 | ath79 | - | 64MB | brick
|
|
|
|
#### Stability
|
|
|
|
* *brick* - this image has been tested and will currently brick your hardware. Avoid for now.
|
|
* *untested* - this image has not been tested on hardware. It may or may not work.
|
|
* *stable* - this image has been tested on hardware. There may still be bugs.
|
|
* *sunset* - this device has been sunsetted and support will be deprecated at some point.
|
|
* *new* - this device is newly supported.
|
|
|
|
The 'target' is a directory to find the image on at http://downloads.arednmesh.org
|
|
|
|
Latest Mikrotik installation options are found at: https://www.arednmesh.org/content/installation-instructions-mikrotik-devices
|
|
|
|
### Ethernet Port usage
|
|
|
|
The standard Ethernet port of an AREDN device uses the following vlan tags. An 802.1Q
|
|
switch is necessary to utilize the vlan tagged networks:
|
|
|
|
* untagged: LAN devices - laptop, ipcam, voip phone, etc.
|
|
* vlan 1: WAN - gateway to connect AREDN network to home network and/or internet (some devices support changing this vlan to an alternate value)
|
|
* vlan 2: DtDLink (device to device) - AREDN network routing between nodes, typically cross band
|
|
|
|
The following devices have enhanced Ethernet port usage. A single cat5 to the device
|
|
could be plugged into ether the 'main' or 'secondary' port with standard port functionality.
|
|
Both ports can be used interchangeably and simultaneously with LAN devices on both ports
|
|
at the same time.
|
|
|
|
If the device's hardware supports POE (Power Over Ethernet) pass-through from main port to secondary
|
|
port, an Advanced Setting option will show to turn on/off. This is useful to power ipCams or other
|
|
mesh nodes by daisy chaining the network cable from one device to another. Then only one network
|
|
cable may be needed to reach 2 or 3 devices on the tower. Be sure to check the power capacity in the
|
|
vendor specifications to not exceed. The first device in the chain will provide the DHCP address to
|
|
all LAN devices on all nodes (because it powers up first).
|
|
|
|
* NanoStation M2 XW
|
|
* NanoStation M5 XW
|
|
* NanoStation M2 XM
|
|
* NanoStation M3 XM
|
|
* NanoStation M5 XM
|
|
* TP-Link CPE210 v1/v1.1
|
|
* TP-Link CPE220 v2
|
|
* TP-Link CPE220 v3
|
|
* TP-Link CPE510 v1/v1.1
|
|
* TP-Link WBS210 v1
|
|
* TP-Link WBS210 v2
|
|
* TP-Link WBS510 v1
|
|
* TP-Link WBS510 v2
|
|
|
|
The Mikrotik hAP AC Lite, Ubiquiti AirRouter, and AirRouter HP are pre-configured with the following VLANs:
|
|
|
|
* Port 1: WAN Port - Packets in/out of this port are expected to be untagged. The node is (by default) configured to receive a DHCP assigned address from a home network, internet, or other foreign network.
|
|
* Port 5: DtDLink Port Mesh Routing -- Connect to another mesh node or 8021.q switch. Packets in/out of this port must be vlan 2 tagged, other packets are ignored.
|
|
* Ports 2-4: LAN devices -- Packets in/out of this port are expected to be untagged. The mesh node will (default) DHCP assign an IP address to your computer, ipCam, voip phone, etc. connected to these ports.
|
|
|
|
|
|
The GL.iNet GL-AR150 and GL-AR300M16 are pre-configured with the following VLANS:
|
|
|
|
* Port labeled "WAN": untagged = AREDN WAN
|
|
* Port labeled "LAN": untagged = AREDN LAN, vlan 2 = DtDLink (device to device)
|
|
|
|
The GL.iNet GL-AR750 is pre-configured with the following ports, left to right:
|
|
|
|
* Left Port with internet globe icon: WAN (untagged)
|
|
* Middle Port with "<..>" icon: DtDLink (vlan 2)
|
|
* Right Port with "<..>" icon: LAN (untagged)
|
|
|
|
IMPORTANT: For Gl.iNet devices, when initially installing AREDN on OpenWRT, you *MUST* uncheck the "Keep Settings" checkbox.
|
|
|
|
## Submitting Bug Reports
|
|
|
|
Please submit all issues to http://github.com/aredn/aredn/issues
|
|
|
|
## Developer Only Information
|
|
|
|
The AREDN firmware is based on OpenWrt with additional packages and patches.
|
|
A Makefile automates the entire process to create firmware images.
|
|
|
|
### Building with Docker
|
|
Installing the Docker environment on your windows/linux/mac machine is a pre-requisite. A docker 'container' has been pre-configured with an aredn linux build environment. Alternative instructions are below if you wish to setup your linux install with the compiler pre-requisites necessary to do the build.
|
|
|
|
To build with docker:
|
|
```
|
|
docker pull arednmesh/builder
|
|
docker run -it --name builder arednmesh/builder
|
|
```
|
|
|
|
To pull an image (or any other file) out of the docker container:
|
|
```
|
|
docker cp builder:/opt/aredn/aredn/firmware/targets/ath79/generic/<image>.bin <local directory>
|
|
```
|
|
|
|
### Build Prerequisites
|
|
|
|
Please take a look at the [OpenWrt documentation](https://openwrt.org/docs/guide-developer/build-system/install-buildsystem)
|
|
for a complete and up to date list of packages for your operating system.
|
|
|
|
On Ubuntu/Debian:
|
|
```
|
|
apt-get install git subversion build-essential libncurses5-dev \
|
|
zlib1g-dev gawk unzip libxml-perl flex wget gettext quilt \
|
|
python libssl-dev shellcheck lua5.1
|
|
```
|
|
|
|
On openSUSE:
|
|
```
|
|
zypper install --type pattern devel_basis
|
|
zypper install git subversion ncurses-devel zlib-devel gawk unzip \
|
|
perl-libxml-perl flex wget gettext-runtime quilt python \
|
|
libopenssl-devel shellcheck lua51
|
|
```
|
|
|
|
On Arch:
|
|
```
|
|
pacman -S base-devel subversion zlib unzip perl-xml-libxml wget \
|
|
quilt openssl shellcheck lua51 git
|
|
```
|
|
|
|
### Building firmware images
|
|
|
|
To obtain the source and build the firmware locally use:
|
|
|
|
```
|
|
bash
|
|
git clone https://github.com/aredn/aredn.git
|
|
cd aredn
|
|
vi config.mk # enter your callsign, etc.
|
|
# build default legacy ath79 target ubnt and tplink images
|
|
make
|
|
# build and add legacy ath79 target mikrotik images
|
|
make SUBTARGET=mikrotik
|
|
# build and add ath79 target (latest linux kernel) ubnt, tplink, and gl images
|
|
make MAINTARGET=ath79
|
|
```
|
|
|
|
Building the images may take minutes or hours depending on the machine.
|
|
For more details see [build options](https://openwrt.org/docs/guide-developer/build-system/use-buildsystem).
|
|
Review the build options in config.mk: `-j <nuMBer of cores + 1>`.
|
|
`V=s` will give more verbose error messages.
|
|
|
|
An internet connection is required during the build process. A good internet
|
|
connection can improve the build time.
|
|
|
|
You need approximately 10GB of space for the build.
|
|
|
|
### How to build prior builds of AREDN
|
|
|
|
Prior AREDN images can be rebuilt. Replace one of the following after
|
|
the "cd aredn" command above:
|
|
|
|
AREDN release 3.22.12.0
|
|
|
|
```
|
|
git checkout 3.22.12.0
|
|
```
|
|
|
|
AREDN release 3.22.8.0
|
|
|
|
```
|
|
git checkout 3.22.8.0
|
|
```
|
|
|
|
AREDN release 3.22.6.0
|
|
|
|
```
|
|
git checkout 3.22.6.0
|
|
```
|
|
|
|
AREDN release 3.22.1.0
|
|
|
|
```
|
|
git checkout 3.22.1.0
|
|
```
|
|
|
|
AREDN release 3.21.4.0
|
|
|
|
```
|
|
git checkout 3.21.4.0
|
|
```
|
|
|
|
AREDN release 3.20.3.1
|
|
|
|
```
|
|
git checkout 3.20.3.1
|
|
```
|
|
|
|
AREDN release 3.20.3.0
|
|
|
|
```
|
|
git checkout 3.20.3.0
|
|
```
|
|
|
|
AREDN release 3.19.3.0
|
|
|
|
```
|
|
git checkout 3.19.3.0
|
|
```
|
|
|
|
AREDN release 3.18.9.0
|
|
|
|
```
|
|
git checkout 3.18.9.0
|
|
```
|
|
|
|
AREDN release 3.16.2.0
|
|
|
|
```
|
|
git checkout 3.16.2.0
|
|
```
|
|
|
|
AREDN release 3.16.1.1
|
|
|
|
```
|
|
git checkout 3.16.1.1-make
|
|
```
|
|
|
|
AREDN build 176
|
|
|
|
```
|
|
git checkout 91ee867
|
|
```
|
|
|
|
Return to most current changes
|
|
|
|
```
|
|
git checkout main
|
|
```
|
|
|
|
### Directory Layout
|
|
|
|
```
|
|
Included in the git Repo:
|
|
config.mk <- build settings
|
|
openwrt.mk <- which openwrt repo and branch/tag/commit to use
|
|
feeds.conf/ <- custom package feeds (edit to point to your clone of aredn_packages)
|
|
files/ <- file system in AREDN created images, most customizations go here
|
|
patches/ <- patches to openwrt go here
|
|
scripts/ <- tests and other scripts called from the build
|
|
configs/ <- definitions of features in the devices' kernel and what packages to include
|
|
Makefile <- the build definition
|
|
README.md <- this file
|
|
|
|
Created by the build:
|
|
openwrt/ <- cloned openwrt repository
|
|
firmware/ <- the build will place the images here
|
|
results/ <- code checks and other test results in jUnit xml format
|
|
```
|
|
|
|
### Patches with quilt
|
|
|
|
The patches directory contains quilt patches applied on top of the
|
|
openwrt git repo defined in config.mk.
|
|
|
|
If a patch is not yet included upstream, it can be placed in the `patches` directory with
|
|
the `quilt` tool. Please configure `quilt` as described in
|
|
[OpenWrt Quilt](https://openwrt.org/docs/guide-developer/build-system/use-patches-with-buildsystem).
|
|
|
|
#### Add, modify or delete a patch
|
|
|
|
Switch to the openwrt directory:
|
|
|
|
```bash
|
|
cd openwrt
|
|
```
|
|
Now you can use the `quilt` commands.
|
|
|
|
##### Example: add a patch
|
|
|
|
```bash
|
|
quilt push -a # apply all patches
|
|
quilt new 008-awesome.patch # tell quilt to create a new patch
|
|
quilt edit somedir/somefile1 # edit files
|
|
quilt edit somedir/somefile2
|
|
quilt refresh # creates/updates the patch file
|
|
```
|
|
|
|
## Submitting new features and patches to AREDN
|
|
|
|
The high level steps to submit to this repository https://github.com/aredn/aredn are:
|
|
|
|
1) create a github account and 'fork' this repo
|
|
2) git commit a change into your fork, e.g. http://github.com/ae6xe/aredn
|
|
3) create a pull request for http://github.com/aredn/aredn to consider your change
|
|
|
|
|
|
|