Update README.md with markdown formatting
Change-Id: Ifce0c0f7d7ee0e01c7add6fe3324779f331766ca
Reviewed-on: https://weave-review.googlesource.com/2180
Reviewed-by: Vitaly Buka <vitalybuka@google.com>
diff --git a/README.md b/README.md
index c78283b..6fee848 100644
--- a/README.md
+++ b/README.md
@@ -1,131 +1,150 @@
-Overview
---------
-libWeave is the library with device side implementation of Weave
-protocol.
+# Overview
-Sources
--------
+libWeave is the library with device side implementation of Weave protocol.
+
+# Sources
+
Sources are located in git repository at
https://weave.googlesource.com/weave/libweave/
-Install Repo
--------
-1. Make sure you have a bin/ directory in your home directory
+# Install Repo
+
+Make sure you have a bin/ directory in your home directory
and that it is included in your path:
- mkdir ~/bin
- PATH=~/bin:$PATH
+```
+mkdir ~/bin
+PATH=~/bin:$PATH
+```
-2. Download the Repo tool and ensure that it is executable:
+Download the Repo tool and ensure that it is executable:
- curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
- chmod a+x ~/bin/repo
+```
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+chmod a+x ~/bin/repo
+```
-Checkout code
--------
- repo init -u https://weave.googlesource.com/weave/manifest
- repo sync
+# Checkout code
-Directory structure
--------------------
-Includes to be used by device code:
- include/
+```
+repo init -u https://weave.googlesource.com/weave/manifest
+repo sync
+```
-Implementation sources:
- src/
+# Directory structure
-Example of device code:
- examples/
-
-Dependencies:
- third_party/
-
-Build files:
- libweave_standalone.gyp
- libweave_common.gypi
-
-Quick start on Debian/Ubuntu
-----------------------------
-
-Install prerequisites:
-
- examples/prerequisites.sh
-
-Build library, tests, run tests, build example:
-
- examples/build.sh
-
-Execute example (check examples/daemon/README for details):
-
- sudo out/Debug/weave_daemon
+| Path | Description |
+|----------------|------------------------------------|
+| include/ | Includes to be used by device code |
+| src/ | Implementation sources |
+| examples/ | Example of device code |
+| third_party/ | Dependencies |
+| \*.gyp\* files | Build files |
-Prerequisites
--------------
-Common:
+# Quick start on Debian/Ubuntu
- autoconf
- automake
- binutils
- libtool
- gyp
- libexpat1-dev
+### Install prerequisites
-For tests:
+```
+examples/prerequisites.sh
+```
- gtest
- gmock
+### Build library, tests, run tests, build example
-For examples:
+```
+examples/build.sh
+```
- hostapd
- libavahi-client-dev
- libcurl4-openssl-dev
- libevent 2.1.x-alpha
+### Execute example (see this [README](examples/daemon/README.md) for details):
+
+```
+sudo out/Debug/weave_daemon
+```
+
+# Prerequisites
+
+### Common
+
+ - autoconf
+ - automake
+ - binutils
+ - libtool
+ - gyp
+ - libexpat1-dev
+
+### For tests
+
+ - gtest
+ - gmock
+
+### For examples
+
+ - hostapd
+ - libavahi-client-dev
+ - libcurl4-openssl-dev
+ - libevent 2.1.x-alpha
-Compiling
----------
-Everywhere below Debug can be replaced with Release.
+# Compiling
-Generate build files:
+### Generate build files
- gyp -I libweave_common.gypi --toplevel-dir=. --depth=. \
- -f make libweave_standalone.gyp
+```
+gyp -I libweave_common.gypi --toplevel-dir=. --depth=. \
+ -f make libweave_standalone.gyp
+```
-Build library with tests:
+### Build library with tests
- make
+```
+make
+```
-Build library only:
+### Build library only
- make libweave
+```
+make libweave
+```
-Testing
--------
-Run unittests tests:
+# Testing
- out/Debug/libweave_testrunner
- out/Debug/libweave_exports_testrunner
+### Run unittests tests
-Making changes
---------------
+```
+out/Debug/libweave_testrunner
+out/Debug/libweave_exports_testrunner
+```
+
+# Making changes
+
+### Configure git
Make sure to have correct user in local or global config e.g.:
- git config --local user.name "John Doe"
- git config --local user.email johndoe@example.com
+```
+git config --local user.name "User Name"
+git config --local user.email user.name@example.com
+```
-Start local branch
+### Start local branch
- repo start <branch name> .
+```
+repo start <branch name> .
+```
-Edit code and commit locally e.g.:
+### Edit code and commit locally e.g.
- git commit -a -v
+```
+git commit -a -v
+```
-Upload CL:
+### Upload CL
- repo upload .
+```
+repo upload .
+```
+
+### Request code review
Go to the url from the output of "repo upload" and add reviewers.
diff --git a/examples/daemon/README.md b/examples/daemon/README.md
index feb57a7..a447082 100644
--- a/examples/daemon/README.md
+++ b/examples/daemon/README.md
@@ -1,39 +1,43 @@
-Overview
---------
+# Overview
+
The wrapper implements OS dependent services for libweave
-Building
---------
- - prepare environment
- examples/prerequisites.sh
- - build daemon
- examples/build.sh
- - binaries for daemon are in the directory
- out/Debug/
+# Building
-Prepare Host OS
----------------
-enable user-service-publishing in avahi daemon
- file: /etc/avahi/avahi-daemon.conf
- check: disable-user-service-publishing=no
- restart: sudo service avahi-daemon restart
+### prepare environment
+```
+examples/prerequisites.sh
+```
-Acquire Registration Ticket
----------------------------
-Goto https://developers.google.com/oauthplayground/
- - "Step 1", paste to "Authorize APIs" with
- https://www.googleapis.com/auth/clouddevices
- click "Authorize APIs", then "Allow" to get an
- "authorization code"
- - "Step 2", "Exchange authorization code for tokens"
- - "Step 3", obtain a registration ticket for your new weave device
- HTTP Method: POST
- Request URI: https://www.googleapis.com/weave/v1/registrationTickets
- Enter request body:
- {
- "userEmail": "me"
- }
- then "Send the request", a ticket id will be returned in
+### build daemon
+```
+examples/build.sh
+```
+Binaries for daemon are in the out/ directory.
+
+# Prepare Host OS
+
+### Enable user-service-publishing in avahi daemon
+Set disable-user-service-publishing=no in /etc/avahi/avahi-daemon.conf
+
+#### restart avahi
+```
+sudo service avahi-daemon restart
+```
+
+# Control device with the cloud
+
+### Generate registration ticket
+- Go to [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
+- "Step 1": Paste https://www.googleapis.com/auth/clouddevices and click to "Authorize APIs"
+- "Step 2": Click "Exchange authorization code for tokens"
+- "Step 3": Fill the form:
+ * HTTP Method: POST
+ * Request URI: https://www.googleapis.com/weave/v1/registrationTickets
+ * Enter request body: ```{"userEmail": "me"}```
+ * Click "Send the request", a ticket id will be returned in
+
+```
{
"userEmail": "user@google.com",
"kind": "weave#registrationTicket",
@@ -42,65 +46,74 @@
"creationTimeMs": "1443204694855",
"id": "93019287-6b26-04a0-22ee-d55ad23a4226"
}
- Note: the ticket "id" is not used within 240 sec, it will be expired.
+```
+- Note: the ticket "id" is not used within 240 sec, it will be expired.
-Register device to cloud
-------------------------
- - copy the ticket "id" generated above
- 93019287-6b26-04a0-22ee-d55ad23a4226
- - go to terminal, register and start the daemon with
+### Register device to cloud
+
+- Copy the ticket "id" generated above: ```93019287-6b26-04a0-22ee-d55ad23a4226```
+- Go to terminal, register and start the daemon with
+
+```
sudo out/Debug/weave_daemon_sample --registration_ticket=93019287-6b26-04a0-22ee-d55ad23a4226
+```
- you should see something like:
- Publishing service
- Saving settings to /var/lib/weave/weave_settings.json
+- See something like:
- note: in second and future runs, --registration_ticket
- options is not necessary anymore
+```
+ Publishing service
+ Saving settings to /var/lib/weave/weave_settings.json
+```
- - get your device id with
- sudo cat /var/lib/weave/weave_settings.json
- you should see
- ...
- "device_id": 0f8a5ff5-1ef0-ec39-f9d8-66d1caeb9e3d
- ...
+- Note: in second and future runs, --registration_ticket options is not necessary anymore
+- Get your device id with
- this device_id shall be used for future communication
- with your device. it does not expire and no need to
- register.
+```
+ sudo cat /var/lib/weave/weave_settings.json
+```
- - verify device is up with Weave Device Manager at
- android: https://play.google.com/apps/testing/com.google.android.apps.weave.management
- chrome: https://chrome.google.com/webstore/detail/weave-device-manager/pcdgflbjckpjmlofgopidgdfonmnodfm
- [need your whitelisted EAP account]
+- See something like:
-Send Command to the Daemon
---------------------------
- - go to the oauthplayground used for registration ticket command
- in "Step 3", send command with
- HTTP Method: POST
- Request URI: https://www.googleapis.com/weave/v1/commands
- Enter request body:
+```
+ ...
+ "device_id": 0f8a5ff5-1ef0-ec39-f9d8-66d1caeb9e3d
+ ...
+```
+
+- Use this device_id for future communication with your device. It does not expire.
+- Verify device is up with Weave Device Managers on
+[Android](https://play.google.com/apps/testing/com.google.android.apps.weave.management),
+[Chrome](https://chrome.google.com/webstore/detail/weave-device-manager/pcdgflbjckpjmlofgopidgdfonmnodfm)
+or [Weave Developpers Console](https://weave.google.com/console/)
+
+### Send Command to the Daemon
+
+- Go to [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
+- "Step 1": Paste https://www.googleapis.com/auth/clouddevices and click to "Authorize APIs"
+- "Step 2": Click "Exchange authorization code for tokens"
+- "Step 3": Fill the form:
+ * HTTP Method: POST
+ * Request URI: https://www.googleapis.com/weave/v1/commands
+ * Enter request body:
+
+```
{
"deviceId": "0f8a5ff5-1ef0-ec39-f9d8-66d1caeb9e3d",
"name": "_sample.hello",
"component": "sample",
"parameters": { "name": "cloud user" }
}
- "Send the request", you command will be "queued" as its "state"
- - verify the command execution observing daemon console logs
+```
- - verify the command history with oauthplayground
- Similar to "Acquire Registration Ticket" section in this document,
- except in "step 3", do:
-
- HTTP Method: GET [not POST anymore]
- Request URI: https://www.googleapis.com/weave/v1/commands?deviceId=0f8a5ff5-1ef0-ec39-f9d8-66d1caeb9e3d
-
- "Send the request", you get all of the commands executed on your
- device, find something like
- "kind": "weave#command",
- "name": "_sample.hello",
- ...
+- "Send the request", you command will be "queued" as its "state"
+- Verify the command execution observing daemon console logs
+- Verify the command usign [Weave Developpers Console](https://weave.google.com/console/)
+- Verify the command history with [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
+- "Step 1": Paste https://www.googleapis.com/auth/clouddevices and click to "Authorize APIs"
+- "Step 2": Click "Exchange authorization code for tokens"
+- "Step 3": Fill the form:
+ * HTTP Method: GET
+ * Request URI: https://www.googleapis.com/weave/v1/commands?deviceId=0f8a5ff5-1ef0-ec39-f9d8-66d1caeb9e3d
+ * Click "Send the request", you get all of the commands executed on your device.
