Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 362 lines (260 sloc) 13.819 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361
OpenWrt and Devolo dLAN USB Extender building, flashing and configuration instructions.
======================================================================================
Florian Fainelli <florian@openwrt.org>
Version 1.0, Nov. 2012

This document describes the various steps involved in building
flashing and configuring an OpenWrt firmware for the Devolo
dLAN USB Extender device. This device is using a Moschip MCS8140
System-on-a-chip, which is only supported for the moment by the
OpenWrt development version (called trunk later in this document).

[[X1]]

1) Building OpenWrt
-------------------

1.1) Prerequisites
~~~~~~~~~~~~~~~~~~

In order to build OpenWrt, we recommend using a Linux-based machine with
the usual GNU software development tools such as GCC, Make, ncurses etc..
Use your Linux distribution package manager to install these tools. If
there is any missing tool, OpenWrt will check for it and warn if it find
it missing or ineadequate.

To download the OpenWrt sources the subversion and git tools are required.

*Note:* OpenWrt can also be built under FreeBSD or MacOSX, but their are not
officially supported as build platforms.

1.2) Checking out OpenWrt sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The OpenWrt sources are made available using subversion. Complete
instructions can be found here: https://dev.openwrt.org/wiki/GetSource

You should start defining a directory which will serve as the root directory
for the OpenWrt sources and build system.

OpenWrt does not require being built as root, and will actually prevent you
from building it as root. Assuming you are in your home directory ($HOME),
create a directory in which you will download OpenWrt sources:

$ cd $HOME
$ mkdir -p projects/openwrt
$ cd projects/openwrt

We can now start downloading the OpenWrt sources in this current directory
by doing the following:

$ svn co svn://svn.openwrt.org/openwrt/trunk/

The sources are now checked out, and are ready for building.

1.3) Adding Third party software for PowerLine Communication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prior to building OpenWrt we need to download third-party software, which
is responsible for making the Power Line Communication (PLC) part of the
Devolo dLAN USB Extender device working.

The Power Line Communication part of the dLAN USB Extender device requires
some proprietary software which is made available using an OpenWrt "feed".

A feed should be seen as a repository in which packages maintained by third
parties can be added.

Move to the previously downloaded OpenWrt sources at step 1.2) using the
following:

$ cd trunk/

At the root of this directory, edit the file feeds.conf.default, which is
going to contain the download method, name and url of the feed. Alternatively
you can use the following:

$ echo "src-git dlan https://github.com/ffainelli/dlan-usb-extender-3rd-party.git"
>> feeds.conf.default

The first column tells the feeds script how to download (using git), the second
is a name to reference to this "feed" and the third one is the url where to find
the package makefiles.

Once this is done, we need to get a copy of this feed, in order to do so, use
the following command:

$ ./scripts/feeds update dlan

Now that we have got a copy of the feed, we can add the packages to the build
system:

$ ./scripts/feeds install foot

Since foot depends on confmgr and hpav-firmware to run, these packages are
listed as dependencies and the feeds script handles that for us.

foot also depends on another package called `hpavcfg` which is available in a
different feed which is the default repository for OpenWrt packages. To install
this package we need to proceed with the following:

$ ./scripts/feeds update packages
$ ./scripts/feeds install hpavcfg

The build system will have integrated these packages just like regular packages.

1.4) Building OpenWrt
~~~~~~~~~~~~~~~~~~~~~

Prior to building OpenWrt, we need to instruct the build system about which
target we want to build for. In order to that, remain in the same directory
($HOME/projects/openwrt/trunk) and run the following:

$ make menuconfig

You will be prompted with a console-based menu with which we will interact for
configuring OpenWrt propertly.

In the Target System menu, choose "Moschip MCS814x" and press enter. The OpenWrt
build system has already preconfigured a certain number of base packages, but
still we need to tell the build system to also include the dLAN USB Extender
specific package set.

In order to do that, go to the "Target Profile" menu, and switch from "Generic"
to "Devolo dLAN USB Extender", this will now select the "foot" package which is
required for proper Power Line Communication operation.
To select the "hpavcfg" package, now go to the "Network" section and type "y"
as well.

Exit and save the configuration.

We are now ready to build the entire firmware image, to do so, just run:

$ make

The build usually takes some time (up to one hour on a relatively recent
build machine) due to the building of the toolchain, packages and kernel.

Once the build is done, we will have built the base firmware, which contains
the Linux kernel, and all the selected packages.

2) Flashing the device with an OpenWrt firmware
-----------------------------------------------

Now that we have successfully completed the OpenWrt build for the Devolo dLAN
USB Extender device, we can prepare an USB flash stick to flash our device
with this OpenWrt firmware.

2.1) Locating and preparing the OpenWrt firmware image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Remain in the same directory ($HOME/projects/openwrt/trunk), once the build is
finished you will find several files in the directory `bin/mcs814x/` relative
to this directory which correspond to various files useful for flashing the
target.

OpenWrt produces an image which can be used by the dLAN USB Extender firmware
with the USB autoupdate feature. This image is:

`bin/mcs814x/openwrt-mcs814x-dlan-usb-extender-upgrade-squashfs.bin`

You will need to prepare an USB Stick with specific parameters in order to use
the USB autoupdate feature of the dLAN USB Extender. The specific parameters of
this USB stick are:

an unique FAT32 partition with the label autoupdate. You should then copy the
file `bin/mcs814x/openwrt-mcs814x-dlan-usb-extender-upgrade-squashfs.bin` to
this USB stick and name the file autoupdate_image. You can for instance use the
following:

$ cp bin/mcs814x/openwrt-mcs814x-dlan-usb-extender-upgrade-squashfs.bin
/media/AUTOUPDATE/autoupdate_image

2.2) Flashing the dLAN USB Extender
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your device is now ready to be flashed with this OpenWrt firmware, in order to
let the autoupdate feature start, just plug in the USB key, and power cycle
your device.

The USB LED will start blinking fast indicating that it is reading the firmware
file from the USB stick.

3) Configuring your OpenWrt device
----------------------------------

By default the device will come up on the Power Line Communication network with
the following parameters:

---------------------------------------
Ethernet MAC address: 00:0B:3B:00:00:01
IP address: 192.168.1.1
Netmask: 255.255.255.0
Homeplug AV NPW: HomePlugAV
Telnet access with no password
---------------------------------------

3.1) Configuring IP networking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For all OpenWrt devices IP networking is configured using the file
`/etc/config/network` and contains the following:

--------------------------------------
config interface lan
        option ifname eth0
        option proto static
        option ipaddr 192.168.1.1
        option netmask 255.255.255.0
-------------------------------------

The Ethernet MAC address of the interface can be changed at any time by using
the configuration option "macaddr", this option should be added to the file
`/etc/config/network`, like this:

-----------------------------------------
option macaddr 00:0B:3B:00:00:01
-----------------------------------------

If you want to configure your device to instead obtain its IP address
via DHCP, just replace the "static" protocol by "dhcp". You should then issue
the following command for the settings to be applied:

$ /etc/init.d/network restart


3.2) Configuring Power Line Communication networking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Power Line Communication networking is configured through several means among
them:

* using the file /etc/config/foot
* using the push button located at the back of the device
* using the hpavcfg utility

3.2.1) Using /etc/config/foot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The file /etc/config/foot is responsible for configuring the PLC chip with
initial parameters on startup, the most important parameters is the DPW
(Security ID or device password). Once the settings have been
changed, you will need to powercycle the device for the PLC chip to fetch its
new parameters, this can be done using the following command:

$ /etc/init.d/foot restart

3.2.2) Using the push button
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To associate your device with an existing Homeplug AV network, you should press
another device push button, then press the push button on the device you want
to associate as well. Both Power LEDS will be blinking, and you should then
see the PLC LEDs start blinking to indicate trafic is properly emitted and
received by devices.

3.2.3) Using the hpavcfg utility
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The hpavcfg utility is a ligthweight configuration utility which is able to send
a NPW to either a local or remote device. To change a device's NPW, you should
issue the following command:

$ hpav_cfg -n <network passphrase> <network interface>

by default, hpav_cfg will use the HomePlugAV broadcast MAC address for sending
this command. If you want to target a single device, use the "-a" switch of
the utility, as show below:

$ hpav_cfg -n <network passphrase> -a 00:11:22:33:44:55 <network interface>

4) Using wmbus-repeater with the dLAN USB Extender
--------------------------------------------------

wmbus-repeater is a software package allowing Open Metering System repeater
functionnality between two host devices using a network interface on one side
and an Amber Wireless USB stick (AMB8465 devices) on the other side.

OMS wireless data received on the USB stick can be forwarded back to the
network interface and vice versa, OMS data received over the network interface
can be sent to the USB stick and then over the OMS wireless network.

4.1) Typical OMS network topology and functionnality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To repeat OMS data, the setup must be comprised of two USB sticks and two dLAN
USB Extender devices at least. The dLAN USB Extender devices must have been
preliminary paired to be connected to each other in the same HomePlug AV
network (see documentation above to pair the dLAN USB Extender devices).

The typical setup will look like this:

-------------------------------------------------------------------------------
--------------- ----------------- ----------------- --------------
| USB stick 1 | <-> | dLAN USB Ext 1| <==> | dLAN USB Ext 2| <->| USB Stick 2 |
--------------- ----------------- ----------------- --------------
  T1 meter mode Same HomePlug AV network T2 other mode
-------------------------------------------------------------------------------

See section 4.2 below to see how to configure wmbus-repeater in T1 meter and
T2 other mode.

OMS wireless data sent to USB Stick 1, configured as T1 meter mode, will be
sent over the HomePlug AV network interface of dLAN USB Ext 1 and be received
over the HomePlug AV network interface by dLAN USB Ext 2. dLAN USB Ext 2 will
then forward this OMS wireless data to the USB STick 2 attached to it and set
the "hop" counter to 1 (data is repeated).

By combining several times this basic network topology you can very easily
create repeated wmBus networks using the HomePlug AV network as a backbone for
repeating wireless data.

The wmbus-repeater software is handling the repeated packet in such a way
that:

* only packets with a hop counter set to 0 will be repeated
* packets with a hop counter different from 0 will not be repeated

This is to ensure that devices too close to each other, typically a T2 other
device close enough to receive data from two T1 meter emitters will not repeat
twice the same data received both over the HomePlug AV interface and over the
USB stick.

4.2) Configuring wmbus-repeater
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The configuration of the wmbus-repeater software is done in
`/etc/config/wmbus-repeater`. The default configuration is the following:

-------------------------------------
config wmbus-repeater
option device "/dev/ttyUSB0"
option interface "eth0"
option mode "S1
-------------------------------------

Mode can be:

* S1
* S2
* T1meter
* T1other
* T2meter
* T2other
* retain

Depending on your setup and Wireless and HomePlug AV network topology, you will
have to configure the wmbus-repeater daemon to be in one of the mode presented
above. The "retain" mode is a special value which is to be used when you do not
want to change the mode pre-configured in the USB stick.

4.3) Starting/stopping and USB stick hot-plugging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, when a USB stick is hotplugged on a dLAN USB Extender device the
wmbus-repeater software will be started on the corresponding `/dev/ttyUSB<N>`
device with the mode specified in the configuration file
`/etc/config/wmbus-repeater`. You can still control the execution life of
wmbus-repeater by issuing the following commands:

$ /etc/init.d/wmbus-repeater stop
$ /etc/init.d/wmbus-repeater start
Something went wrong with that request. Please try again.