# Overview

## Introduction

The Open Powerline Toolkit (vanilla version) may be downloaded from https://github.com/qca/open-plc-utils.git by any interested party. An advanced version (chocolate version) may be downloaded from the Qualcomm Atheros Customer FTP site by parties having permission to do so. The chocolate version includes special programs that perform advanced engineering, production and maintenance tasks. Within this document, we refer to both versions, collectively, as the toolkit.

The toolkit contains C Language source code and GNU makefiles to compile many useful programs. It also includes Linux shell scripts that use these programs, in various ways, to interrogate, control and manage Qualcomm Atheros INT6000, INT6300, INT6400, AR7400 and later powerline devices. Qualcomm Atheros also provides a similar, but less extensive, toolkit for INT5500 powerline devices.

The toolkit is intended for hardware engineers, verification engineers, field engineers and embedded software developers, consequently, programs are simple and compact. It is not intended for computer novices or retail users. Many customers embed a subset of toolkit programs in products for troubleshooting purposes.

The toolkit includes extensive HTML documentation and online man pages for users who cannot access installed man pages. HTML documentation starts with file docbook/index.html. Online man pages start with file docbook/toolkit.html. Qualcomm Atheros recommends that you add these two pages to your browser favorites for later reference.

All toolkit programs are written in C and have command line intefaces. The source code essentially conforms to ISO/IEC9899:1999. The source tree cleanly compiles using gcc or pcc on Ubuntu, OpenBSD and MacOSX. It also compiles under Microsoft C with the inclusion of special header files. The command line interface conforms to Section 12.2 Utility Syntax Guidelines of The Open Group Base Specification Issue 6 ( IEEE Std 1003.1, 2004 Edition).

The toolkit includes Microsoft Visual Studio .NET project files and solutions files to compile toolkit programs, plus the executable version (`.exe`) of each program and a set of Microsoft installation file (`.msi`) so that the toolkit package comes ready to install and run on any Windows host; however, Qualcomm Atheros does not provide support for Microsoft windows version of this toolkit. Toolkit documentation does provide Windows developers with special guidance on setting up their own Visual Studio projects and solutions, should they want to do that.

## Background

HomePlug AV is an industry standard protocol for powerline communications developed by the HomePlug Powerline Alliance. Qualcomm Atheros manufactures a family of chipsets that conform to that standard and have MII, UART and SPI host interfaces. The INT6x00 and AR7x00 series are flagship members of that chipset family. The principle difference between the chipsets is their boot method, cost and speed. The INT6000 requires onboard NVRAM but the INT6300, INT6400 and AR7400 do not.

The HomePlug AV protocol is based on IEEE-802.3, has ethertype `0x88E1` and uses special message formats. A subset of those message formats is reserved for each chipset vendor to define their own message formats. Qualcomm Atheros uses this vendor-specific subset to communicate between host processors and Qualcomm Atheros devices. This toolkit uses Qualcomm Atheros vendor-specific message formats to communicates with Qualcomm Atheros devices. It also understands Qualcomm Atheros firmware and configuration file formats.

This toolkit sends and receives Qualcomm Atheros vendor-specific messages but not generic HomePlug AV messages. Qualcomm Atheros vendor-specific management message formats are described in the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual. If you do not have a copy of this document then you may request one from Qualcomm Atheros.

## Toolkit Distribution

The Qualcomm Atheros Open Powerline Toolkit is distributed using compressed tape archive files named `open-plc-utils-x.x.x.tar.gz` and `open-plc-utils-x.x.x.tar.bz2` and standard compressed archive file named `open-plc-utils-x.x.x.zip`, where x.x.x is the version number. Archive files ending in `.gz` can be decompressed with the Linux gzip utility. Archive files ending in `.bz2` can be decompressed with the Linux bzip2 utility. Archive files ending in `.zip` can be decompressed using the Linux unzip utility or the Windows WinZip utility. The contents of decompressed archives can be extracted using the Linux tar utility. Recent versions of the Linux tar utility allow decompression and extraction in one operation. The WinZip or 7-zip program may be used to decompress archives and extract contents on Microsoft Windows platforms.

Some Windows network administrators enable security software that removes `.exe` and other executable files from `.zip` archives in transit or in-situ. In that case, Windows user may want to download the `*.tar.gz` archive and use a program like 7zip to unpack the archive file.

The toolkit includes source code, build scripts, documentation and pre-compiled programs for Microsoft Windows. Some third party libraries may also be included to support Microsoft platforms. Although the Microsoft Windows versions of toolkit programs are pre-compiled and ready-to-run, they are not supported because this package is designed for use on Linux platforms.

The Windows installer included in this version of the toolkit needs Microsoft .NET 1.1. Windows versions of toolkit programs that communicate with powerline devices need WinPcap 4.1.2 or later. A copy of Microsoft .NET 1.1 and WinPcap 4.1.2 is included in the `support` folder.

&install; &programs; &folders;

## Packages

The following table lists programs and the release packages that contains them. Packages contain programs of interest to various customer and engineering groups based on the activities that they normally perform. Some groups may need multiple packages. Some packages are restricted.

&packages;

## Toolkit Support

Contact the Qualcomm Atheros System Application Engineering Team if you have questions concerning the content, operation, application or direction of this toolkit on GNU/Linux systems. If you are having trouble communicating with Qualcomm Atheros powerline devices using the toolkit, try following the troubleshooting procedure found later in this document.