Prelude

meshComms is an open source implementation of IEEE 1905.1a that is an output of the Broadband Forum Open Broadband - Multi Access Point (OB-MAP) project. For an overview and information on contributing to the OB-MAP project, please see the github Wiki page for the meshComms repository.

Index

What is this?
Who will find this source code useful?
Legal stuff
What is the IEEE 1905 standard?
1. IEEE 1905 overview
2. IEEE 1905 components
3. Limitations in the IEEE 1905 standard
  1. ALMEs are undefined
  2. Control CMDUs
  3. Unknown destination AL MAC address
Build instructions
1. Linux native compilation
2. Linux cross compilation
Usage instructions on Linux platforms
1. Abstraction Layer Entity
2. High Level Entity
3. Libraries
Hacking
1. Source code organization
  1. Files structure
  2. Code overview
    1. Common component
    2. Factory component
    3. AL component
    4. HLE component
2. Porting to new platforms
3. Protocol extensions
  1. Files structure
  2. Register a group
  3. Code overview
    1. TLVs
    2. Callbacks
      1. CMDU extension
      2. Datamodel extension
Testing
1. Unit tests
2. Static code analysis
3. Runtime analysis
4. Black box tests
  1. Push button configuration
    1. Scenario 1
    2. Scenario 2
    3. Scenario 3
  2. Access Point security settings cloning
    1. TC001
    2. TC002
    3. TC003
    4. TC004
    5. TC005
TODO
Appendix A: OpenWRT tool chain and flash image generation
Appendix B: Installing "minGW"

What is this?

This is a source code repository containing a 100% (or that's what I like to think) IEEE 1905 compliant implementation. It covers both the original 1905 specification as well as the 1905.1a amendment.

If you don't know what the IEEE 1905 standard is all about, I have written a small overview in a later section of this same document.

This implementation has been designed to make it as easy as possible to port it to any platform: all you have to do is provide a dozen or so of functions on which the code depends (such as functions to allocate memory or obtain information regarding a network interface).

In addition to this "easy to port code", all the "platform-specific" functions for the Linux platform are also provided. This means you can now checkout the source code from this repository and make it work right away on almost any Linux distro with minor or no modifications.

So, to make it clear, what you will find in this repository is:

A 1905 implementation that is completely independent from other libraries and, in fact, only needs a handful of additional platform specific functions to run.
That "handful" of additional functions already implemented for the particular case of a standard Linux platform.

Who will find this source code useful?

As of today, I guess the target audience for this repository are developers working on an embedded router who have been assigned the task to "implement" the IEEE 1905 standard because the marketing department foresaw it was a "killer feature".

Right now there doesn't seem to be any other open IEEE 1905 implementation, however there are devices out there which say they are IEEE 1905 compatible.

If you are just about to start yet another closed implementation, I urge you to consider the possibility of contributing to this repository instead. After all, the best way to push a standard forward is to make it easy for everyone to adopt it, right?

In addition, there is another reason to contribute: the IEEE 1905 is not exactly the most refined standard in the world. It contains several holes open to interpretation and some other items that are... well... "strange" at least. Having a common open implementation is useful to "quickly" agree on some of these issues so that the IEEE can later come up to speed (updating a standard is a slow process and pushing from below, from the technical side, is always a good idea).

In the future, maybe this repository will be used to create Linux distro packages than can be automatically installed with a single call to "yum/aptitude/pacman/...".

Legal stuff

This software is covered by the license contained in the "LICENSE" file. Also see the further information contained in the "PROJECT" file (both files are in the same folder as this "README.md").

What is the IEEE 1905 standard?

Even if you think you know what IEEE 1905 is, you should read the next sections.

IEEE 1905 overview

Basically, the idea behind IEEE 1905 is to have a mechanism that lets home devices discover each other and communicate. The purpose? Use optimal paths for data transmission.

For example, let's say we have an ADSL home router with a power line and a WIFI interface. At the other end of the house there is another power line device connected to a computer like this:

    ADSL   --------       WIFI              ----
  =========|Router| ) ) ) ) ) ) ) ) ) ) ) ) |PC|
           --------                         ----
              *                              |
              *                              | Ethernet
              *                              |
              *        Power line         --------------
              * * * * * * * * * * * * * * | power line |
                                          | adapter    |
                                          --------------

If the computer tries to access the Internet... what interface should it use? The Ethernet interface connected to the power line adapter or the WIFI interface?

Note that IEEE 1905 covers other types on interfaces too, such as Ethernet, coax, ...

IEEE 1905 helps devices decide: thanks to the information that travels inside 1905 messages each node in the network knows the network topology, the speed of each interface, if there are congestion problems at some point... etc, and then decides how to route traffic or even tells other devices how to route theirs.

So... IEEE 1905 is "kind of" the IEEE alternative to Microsoft's "Windows Rally" technology (which is what Windows uses to "draw" the network topology when you go to "network properties" and lets it diagnose problems such as "your router is not reachable" and things like that).

On this note, Microsoft offers an open source implementation of the "Windows Rally" stack (I ported it to one custom platform a few years ago)... but it seems like it never really took off or else I suspect the IEEE 1905 standard would probably not have been created... or maybe it would, who knows... At this point we just need to wait and see which one (if any) sticks.

But there is more: another (equally important) of IEEE 1905's main objectives is to make it easy to add new devices to an already secured network. This aspect of IEEE 1905 covers two scenarios:

One "standard" device, no matter its underlying technology (WIFI, power line, other...) can be added to an already encrypted network by pressing two buttons: one on the device to be added and another on any other device from the ones already authenticated (again, no matter its underlying technology). This is similar to today's WPS configuration mechanism (used to add new devices to a WIFI network), in fact IEEE 1905 triggers WPS behind your back for WIFI interfaces (and other mechanisms for other technologies).
One "WIFI access point" device (we are talking about WIFI here exclusively, at least in the current form of the standard) can "clone" the security settings of another (already configured and secured) one so that all "WIFI access points" on the network end up sharing the same SSID and password.

As you can see both of the previous points aim at making it easier for a home user to configure their devices: they just press a button and new devices are added and/or new access points are automatically configured.

The more devices on the network implement IEEE 1905, the more information will be available to decide routes and the easier the configuration of new devices will seem.

As of today (February 2016) the standard consists of two documents:

The original "IEEE Std 1905.1-1023" document.
The later "IEEE P1905.1a/D1, July 2014" update.

Unfortunately they are not freely available.

The source code contained in this repository implements all the functionality detailed in both of these documents.

IEEE 1905 components

What is an IEEE 1905 implementation made of? Well, there are two main components:

The AL (Abstraction Layer) is the component in charge of running the core protocol. It controls a node's interfaces and uses them to send periodic broadcast discovery messages to notify other ALs (running in other devices) about its presence.

Once one of these discovery messages is received from a neighbor, the AL entity starts sending a series of unicast packets to query for all types of additional information: "what interfaces do you have?", "of which type is each of them?", "which other neighbors are you aware of?", etc...

Obviously, the AL is also the one in charge of processing queries and sending the appropriate response when required by other ALs.

All messages sent/received between ALs are called "CMDUs" and depending on their type they encapsulate one or more specific "TLV" ("type-length-value") blobs. For example, the CMDU that is used to search for WIFI access points registrars includes a TLV that specifies which WIFI band (2.4 GHz or 5 GHz) the node performing the search supports (

MeshComms

Install / Use

README