Skip to content

Commit

Permalink
Update readme (#78)
Browse files Browse the repository at this point in the history 
This commit enhances the overall quality of the readme files, especially the transport service readme.
  • Loading branch information
@PFigs
PFigs authored Jul 19, 2019
1 parent 1168c08 commit e88bca1
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 80 deletions.
184 changes: 115 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Wirepas Linux Gateway

[![Build Status](https://travis-ci.com/wirepas/gateway.svg?branch=master)](https://travis-ci.com/wirepas/gateway) [![Documentation Status](https://readthedocs.org/projects/wirepas-gateway/badge/?version=latest)](https://wirepas-gateway.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://travis-ci.com/wirepas/gateway.svg?branch=master)](https://travis-ci.com/wirepas/gateway)

This repository contains Wirepas' reference gateway implementation, which
relies on a set of services to exchange data from/to a Wirepas Mesh network
Expand All @@ -19,35 +19,44 @@ apis involved at each step.

**Figure 1 -** Gateway services overview.


## Cloning this repository

This repository depends on two other projects, [c-mesh-api][wirepas_c_mesh_api]
and [backend-apis][wirepas_backend_apis].
The [c-mesh-api][wirepas_c_mesh_api] contains the library used by the sink service, which interfaces

The [c-mesh-api][wirepas_c_mesh_api] contains the library used by the sink
service, which interfaces
with the sink devices. The backend-apis contains api and message wrapper
over the protocol buffers that are transmitted over MQTT.

When cloning this repository and its dependencies you can opt for:
To clone this repository please ensure you have the [repo tool][repo_tool]
installed and type the following:

- Using [repo tool][repo_tool]
and the [manifest repository][wirepas_manifest]

> repo init -u https://github.com/wirepas/manifest.git -m gateway.xml
```shell
repo init -u https://github.com/wirepas/manifest.git -m gateway.xml
```

or
or for organization members and collaborators:

> repo init -u [email protected]:wirepas/manifest.git -m gateway.xml
```shell
repo init -u [email protected]:wirepas/manifest.git -m gateway.xml
```

afterwards download the repositories with
afterwards download the repositories with

> repo sync
```shell
repo sync
```

To clone a particular tag, vX.Y.Z, please use repo's *-b* switch as follows
To clone a particular version branch, vX.Y.Z, please use repo's *-b*
switch as follows:

> repo init (...) -b refs/tags/vX.Y.Z
```shell
repo init (...) -b refs/heads/vX.Y.Z
```

Usage of repo is also documented in the release Dockerfiles (see [Dockerfile][here_container_dockerfile])
Usage of repo is also documented in the release
Dockerfiles (see [Dockerfile][here_container_dockerfile])

## Linux Requirements

Expand Down Expand Up @@ -102,49 +111,60 @@ from com.wirepas.sink.conf:
<policy user="wirepas">
```

*It is recommended to restart your gateway once this file is copied*
*It is recommended to restart your gateway once this file is copied.*

### Transport service

Transport service is implemented in python 3 and
is delivered as a Python wheel and a python tar.gz archive.
tar.gz is used for the gateway part as it includes Python c extension that must
be built at installation time.
Transport service is implemented in python 3 and is delivered as a
Python wheel, either through [PyPi][wirepas_gateway_pypi] or the
[release section of this repository][here_releases].

The library contains a c extension which will be compile upon installation.
Please ensure that you have met all the build requirements prior to
attempting the installation with:

```shell
pip3 install wirepas_messaging-*.whl
```
or

```shell
pip3 install wirepas_gateway-*.tar.gz
```

If you wish to build the wheel yourself, please refer to the
[transport's service readme file][here_transport_readme].

## Configuration and starting services

### Sink service configuration

A sink service must be started for each connected sink on Gateway:

sink_service/build/sinkService -p <uart_port> -b <bitrate> -i <sink_id>
```shell
sink_service/build/sinkService -p <uart_port> -b <bitrate> -i <sink_id>
```

Parameters are:

- **uart_port:** uart port path (default /dev/ttyACM0)
- **bitrate:** bitrate of sink uart (default 125000)
- **sink_id:** value between 0 and 9 (default 0).
- **uart_port:** uart port path (*default:* /dev/ttyACM0)
- **bitrate:** bitrate of sink uart (*default:* 125000)
- **sink_id:** value between 0 and 9 (*default:* 0).

If multiple sinks are present, they must have a different sink_id
If multiple sinks are present, they must have a different *sink_id*.

### Transport service configuration

Parameters can be set from cmd line or from a setting file in YAML format.
To get an exhausted list of parameters, please run:
Parameters can be set from command line or from a setting file in YAML format.
To get an the full list of parameters, please run:

```shell
wm-gw --help
```

#### From cmd line
#### From command line

Here is an example to start the transport module from cmd line:
Here is an example to start the transport module from the command line:

```shell
wm-gw \
Expand All @@ -159,30 +179,36 @@ Here is an example to start the transport module from cmd line:

where:

- **server:** IP or hostname where the MQTT broker is located
- **mqtt_hostname:** Hostname or IP where the MQTT broker is located

- **port:** MQTT port (default: 8883 (secure) or 1883 (local))
- **mqtt_port:** MQTT port

- **user:** MQTT user
- **mqtt_username:** MQTT user

- **password:** MQTT password
- **mqtt_password:** MQTT password

- **gwid:** the desired gateway id, instead of a random generated one.
- **gateway_id:** the desired gateway id, instead of a random generated one.

> It must be unique for each gateway reporting to same broker.
- **ignored endpoints list:** Destination endpoints list to ignore (not published)
- **ignored_endpoints_filter:** destination endpoints list to ignore
(not published)

*Example:*
To filter out destination endpoints 1, 2, 10, 11, 12:

> --ignored_endpoints_filter "\[1,2, 10-12\]" to filter out destination ep 1, 2, 10, 11, 12
```shell
--ignored_endpoints_filter "[1,2, 10-12]"
```

- **whitened endpoints list:** Destination endpoints list to whiten
(no payload content, only size)
- **whitened_endpoints_filter:** destination endpoints list to whiten
(no payload content, only size)

*Example:*

> --whitened_endpoints_filter "\[1,2, 10-12\]" to whiten destination ep 1, 2, 10, 11, 12
To whiten destination ep 1, 2, 10, 11, 12
```shell
--whitened_endpoints_filter "[1,2, 10-12]"
```

#### From configuration file

Expand All @@ -195,32 +221,32 @@ through the settings file. An example of a *settings_file.yml*
file is given below:

```yaml
#
# MQTT brocker Settings
#
mqtt_hostname: <IP or hostname where the MQTT broker is located>
mqtt_port: <MQTT port (default: 8883 (secure) or 1883 (local))>
mqtt_username: <MQTT user>
mqtt_password: <MQTT password>

#
# Gateway settings
#
gateway_id: <the desired gateway id, must be unique for each gateway>
gateway_model: <Custom gateway model, can be omitted>
gateway_version: <Custom gateway version, can be omitted>

#
# Filtering Destination Endpoints
#
ignored_endpoints_filter: <Endpoints to filter out. Ex: [1, 2, 10-12]>
whitened_endpoints_filter: <Endpoints to whiten. Ex: [1, 2, 10-12]>
#
# MQTT brocker Settings
#
mqtt_hostname: <IP or hostname where the MQTT broker is located>
mqtt_port: <MQTT port (default: 8883 (secure) or 1883 (local))>
mqtt_username: <MQTT user>
mqtt_password: <MQTT password>
#
# Gateway settings
#
gateway_id: <the desired gateway id, must be unique for each gateway>
gateway_model: <Custom gateway model, can be omitted>
gateway_version: <Custom gateway version, can be omitted>
#
# Filtering Destination Endpoints
#
ignored_endpoints_filter: <Endpoints to filter out. Ex: [1, 2, 10-12]>
whitened_endpoints_filter: <Endpoints to whiten. Ex: [1, 2, 10-12]>
```

### Optional

Launch local gateway process to see messages received from sinks at Dbus level
It can be launched from command line:
Launch local gateway process to see messages received from sinks at Dbus
level. It can be launched from the command line with:

```shell
wm-dbus-print
Expand All @@ -239,13 +265,13 @@ in the repo tool's manifest.
To make a development build type:
```bash
[IMAGE_NAME=wirepas/gateway-x86:edge] docker-compose -f container/dev/docker-compose.yml build
[IMAGE_NAME=wirepas/gateway-x86:edge] docker-compose -f container/dev/docker-compose.yml build
```
If you want to build a stable image for x86 type:
```bash
docker-compose -f container/stable/x86/docker-compose.yml build
docker-compose -f container/stable/x86/docker-compose.yml build
```
Alternatively you can use our [ci tool][here_ci_docker_build].
Expand All @@ -254,7 +280,9 @@ We also have pre-built images available from docker hub under the
following registries:
[wirepas/gateway][dockerhub_wirepas]: multi architecture registry
[wirepas/gateway-x86][dockerhub_wirepas_x86]: x86 architecture registry
[wirepas/gateway-rpi][dockerhub_wirepas_rpi]: arm/rpi architecture registry
## Starting docker services
Expand All @@ -265,15 +293,19 @@ between both services. For that reason you will have to copy the
[dbus manifest][here_dbus_manifest] to your host's and change the policy
user to reflect what is used within the docker-compose.
After configuring your host's dbus, review the [service settings file.][here_container_env]
The environment parameters will be evaluated by the [container's entry point][here_container_entrypoint]
After configuring your host's dbus, review the
[environment file][here_container_env] where you can define settings for the
sink and transport service.

The environment parameters will be evaluated by
the [container's entry point][here_container_entrypoint]
and passed on to the sink and transport service.
Please ensure that you define the correct password and MQTT credentials and
launch the services with:
```shell
[IMAGE_NAME=wirepas/gateway-x86:edge] docker-compose -f container/dev/docker-compose.yml up [-d]
[IMAGE_NAME=wirepas/gateway-x86:edge] docker-compose -f container/dev/docker-compose.yml up [-d]
```
To view the logs, use
Expand All @@ -288,23 +320,37 @@ or specify which container you want to view the logs from with
docker logs [container-name]
```
## Contributing
We welcome your contributions!
Please read the [instructions on how to do it][here_contribution]
and please review our [code of conduct][here_code_of_conduct].
## License
Wirepas Oy licensed under Apache License, Version 2.0 See file LICENSE for
full license details.
Wirepas Oy licensed under Apache License, Version 2.0 See file
[LICENSE][here_license] for full license details.
[here_contribution]: https://github.com/wirepas/gateway/blob/master/CONTRIBUTING.md
[here_code_of_conduct]: https://github.com/wirepas/gateway/blob/master/CODE_OF_CONDUCT.md
[here_license]: https://github.com/wirepas/gateway/blob/master/LICENSE
[here_img_overview]: https://github.com/wirepas/gateway/blob/master/img/wm-gateway-overview.png?raw=true
[here_ci_docker_build]: https://github.com/wirepas/gateway/blob/master/.ci/build-images.sh
[here_releases]: https://github.com/wirepas/gateway/releases
[here_container]: https://github.com/wirepas/gateway/tree/master/container/
[here_container_dockerfile]: https://github.com/wirepas/gateway/tree/master/container/Dockerfile
[here_container_env]: https://github.com/wirepas/gateway/tree/master/container/wm_gateway.env
[here_dbus_manifest]: https://github.com/wirepas/gateway/blob/master/sink_service/com.wirepas.sink.conf
[here_container_entrypoint]: https://github.com/wirepas/gateway/blob/master/container/docker-entrypoint.sh
[here_transport_readme]: https://github.com/wirepas/gateway/blob/master/python_transport/README.md
[repo_tool]: https://source.android.com/setup/develop/repo
[wirepas_manifest]: https://github.com/wirepas/manifest
[wirepas_c_mesh_api]: https://github.com/wirepas/c-mesh-api
[wirepas_backend_apis]: https://github.com/wirepas/backend-client
[wirepas_gateway_pypi]: https://pypi.org/project/wirepas-gateway
[dockerhub_wirepas]: https://hub.docker.com/r/wirepas/gateway
[dockerhub_wirepas_x86]: https://hub.docker.com/r/wirepas/gateway-x86
Expand Down
45 changes: 36 additions & 9 deletions python_transport/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,44 @@
# Installation
# Wirepas Gateway Transport Service
[![Documentation Status](https://readthedocs.org/projects/wirepas-gateway/badge/?version=latest)](https://wirepas-gateway.readthedocs.io/en/latest/?badge=latest)

To install this package in development mode, please run

pip install -e .
## Building the wheel

To build the source distribution and wheel file, make sure you have the
wheel package installed

pip install wheel

```shell
pip install wheel
```
and then run

py3clean .
python3 setup.py clean --all
python3 setup.py sdist bdist_wheel
```shell
py3clean .
python3 setup.py clean --all
python3 setup.py sdist bdist_wheel
```

A convenience script is available from the [utils folder][here_utils_wheel].

## Installation

Before you attempt to build and install this package, please ensure that
you have [all the requirements met][wm_gateway_requirements].

We highly recommend that you make your installation under a python virtual
environment such as [virtualenv][virtualenv] or [pipenv][pipenv].

To install this package run (use -e for development mode)

pip install \[-e\] .

## Starting the service

Please read on
[how to configure and start the transport service][wm_gateway_transport_conf]

[wm_gateway_transport_conf]: https://github.com/wirepas/gateway/blob/master/README.md#transport-service-configuration
[wm_gateway_requirements]: https://github.com/wirepas/gateway/blob/master/README.md#linux-requirements
[here_utils_wheel]: https://github.com/wirepas/gateway/blob/update-readme/python_transport/utils/generate_wheel.sh

[virtualenv]: https://docs.python.org/3/tutorial/venv.html
[pipenv]: https://github.com/pypa/pipenv
Loading

0 comments on commit e88bca1

Please sign in to comment.