Merge pull request #903 from bryant1410/master

Fix broken headings in Markdown files

Author: cco3

documentation/android_client_walkthrough.md

@@ -1,4 +1,4 @@
-##Physical Web Android Client Walkthrough
+## Physical Web Android Client Walkthrough
 An Introduction to the Physical Web Android Client
 
 We start with a high level-description of the user flows and then dive into and detail the specifics of each screen.
@@ -41,18 +41,18 @@ So that’s it! Happy Physical Webbing!
 Please note that this app has been targeting Android L release (21) and has been tested primarily on the Nexus 5.
 
 
-##FCC Stuff
+## FCC Stuff
 
-###FCC Part 15.19
+### FCC Part 15.19
 This device complies with part 15 of the FCC Rules. Operation is subject to The following two conditions: 
 
 1. This device may not cause harmful interference, and 
 2. This device must accept any interference received, including interference that may cause undesired operation.
 
-###FCC Part 15.21
+### FCC Part 15.21
 Any changes or modifications (including the antennas) made to this device that are not expressly approved by the manufacturer may void the user's authority to operate the equipment.
 
-###FCC RF Radiation Exposure Statement
+### FCC RF Radiation Exposure Statement
 This transmitter must not be co-location or operating in conjunction with any other antenna or transmitter.
 
 This equipment complies with FCC RF radiation exposure limits set forth for an uncontrolled environment.

documentation/branding_guidelines.md

@@ -1,10 +1,10 @@
 
 <img src="https://raw.githubusercontent.com/google/physical-web/master/documentation/images/logo/logo-black.png" width="100px">
-#Physical Web™
+# Physical Web™
 If we believe in Moore's Law whatsoever, then small, cheap, connected devices will soon explode into our lives, filling our homes, workplaces, and public spaces. Today, most IoT devices require installing a dedicated app, which simply doesn't scale when you want to interact with a multitude of smart “things” around you every day. The web is a natural fit, offering interaction on demand without the friction and overhead of installation. The Physical Web is an approach to unleash the core superpower of the web, enabling interaction that’s just a tap away.
 
 
-##Branding Guidelines
+## Branding Guidelines
 
 The following guidelines provide you with guidance for using the Physical Web name and the corresponding Physical Web logo. You can use the name and the logo on your website or in print without pre-approval, provided you follow these basic guidelines.
 

documentation/introduction.md

@@ -1,4 +1,4 @@
-##The Big Idea
+## The Big Idea
 The Physical Web extends the web we know into the physical world around us. This involves creating an open ecosystem where smart devices can broadcast URLs into the area around them. Any nearby display such as a phone or tablet can then see these URLs and offer them up to the user. It mirrors the basic behavior we have today with a search engine:
 
 * The user requests a list of what's nearby.
@@ -10,18 +10,18 @@ The Physical Web extends the web we know into the physical world around us. This
 
 Even though this is a fairly simple idea, it immediately generates lots of questions:
 
-##0. Wait, why are you an app?
+## 0. Wait, why are you an app?
 This is an early prototype. We are trying to get people to experiment with this at an early stage. Of course, this should be built into all smartphones (and tablets and anything with a screen really). We are building an app for now that tries to not feel like an app. It works in the background so you don't need to use it actively. It just silently monitors beacons that you can browse when you're interested.
 
-##1. Will you be pestering people with alarms?
+## 1. Will you be pestering people with alarms?
 A core principle of this system is **no proactive notifications**. The user will only see a list of nearby devices when they ask. If your phone were to be buzzing constantly as you walked through the mall, it would be very frustrating. Push notifications in general are too easily abused. Of course, the user can opt-in to notifications, we are just saying that by default, the user must ask to see anything nearby.
 
 In addition, we only scan when the screen is on: there is no scanning that goes on when the phone is in your pocket. This is consistent with our 'no interruptions' goal but it also has a large positive impact on power usage. Using this app should have very little impact on your phone's battery life.
 
-##2. Isn't there going to be a big list to choose from?
+## 2. Isn't there going to be a big list to choose from?
 At first, the nearby smart devices will be small but if we're successful, there will be many to choose from and that raises an important UX issue. This is where ranking comes in. Today, we are perfectly happy typing "tennis" into a search engine and getting millions of results back, we trust that the first 10 are the best ones. The same applies here. The phone agent can sort by both signal strength as well as personal preference and history, among many other possible factors. Clearly there is lots of work to be done here. We don't want to minimize this task, but we feel that this simple signal strength ranking can get us very far for the first few versions of this project.
 
-##3. Is this secure/private?
+## 3. Is this secure/private?
 URLs broadcast in the clear so anyone can see them. This is by design. That is why we're initially suggesting this to be used in public spaces. This does raise issues for home use where it would be possible for neighbors to intercept beacons. However, one of the big advantages of URLs is that there are so many ways they can be used to increase their security:
 
 * The URL could be obfuscated (e.g. using a non-branded domain)
@@ -31,15 +31,15 @@ URLs broadcast in the clear so anyone can see them. This is by design. That is w
 
 One of the big values of URLs is that they are so flexible and encourage this further evolution.
 
-##4. What about SPAM?
+## 4. What about SPAM?
 With any system, there will be people that try to exploit it. There will likely be many solutions around this problem but again, we can start with the web. Search engines today have this issue and are fairly effective and displaying the correct web sites in your search results. That same approach would apply here. Combine that with historical results of who clicks on what and it's possible to build a fairly robust ranking model and only show the proper devices. However, there is likely much more we can do here and we hope to encourage other ideas on how to solve this problem in a more robust way.
 
-##5. Why URLs?
+## 5. Why URLs?
 The value of a URL is that it is a known part of the web, very flexible, and most importantly, decentralized. URLs allow anyone to play and no central server to be the bottleneck. This is one of the core principles of the web and critical to keep alive.
 
 That being said, we completely expect others to experiment with a url+ID model that goes through their server (e.g. safeurls.com/?id=12345). That is perfectly acceptable and to be encouraged. Systems like that are likely to provide much better security and vetting of sites. But that is the beauty of URLs, there can be as many of these as you'd like and the system still works seamlessly.
 
-##5.5 Why the web?
+## 5.5 Why the web?
 The Physical Web’s primary value is to enable a device to place at users’ fingertips anything from a tiny piece of location-based information to a full blown web app.
 
 * A dog collar could let you call a service to find the owner.
@@ -51,20 +51,20 @@ The Physical Web’s primary value is to enable a device to place at users’ fi
 
 Each of these examples, taken by itself, is modestly useful. Taken as a whole, however, they imply a vast “long tail” where anything can offer information and utility. Native apps are great for high frequency usage. The web enables people to walk up and use something once with hardly any friction.
 
-##6. Which platforms will you support?
+## 6. Which platforms will you support?
 This is meant to be an extension of the web so it should work on every platform. We expect that each platform will experiment with a different UX to show the nearby devices. For example, the current Android app uses notifications while the iOS app will use lock screen notifications. We hope to see lots of experimentation here on how various platforms choose to show and rank this information.
 
 At this point, we have both an Android and iOS app that is open source. We hope this will be used and ported to other platforms.
 
-##7. Can't the user be tracked?
+## 7. Can't the user be tracked?
 Our current URL broadcast method involves a bluetooth broadcast from each beacon. The user's phone gathers this info without connecting to the beacon. This ensures the user is invisible to all beacons, meaning a user can't be tracked simply by walking past a broadcasting beacon. This was very much by design to keep users silent passage untrackable. However, once the user does click on a URL, they are then known to that website.
 
 The search agent on the phone may keep track of which devices the user taps on so they can improve the ranking in the future. Of course, this too needs to be discussed and then possibly offered to the user as an option so they are in control of how this information is stored.
 
-##8. Why Bluetooth Low Energy?
+## 8. Why Bluetooth Low Energy?
 There are many possible ways to broadcast a URL. This initial version uses Bluetooth Low Energy (BLE) as it is so ubiquitous on mobile phones and tablets today. In addition, it is very energy efficient. There are tiny BLE devices that can broadcast for nearly 2 years on a single coin cell. We are using the standard BLE 'ad packet' to broadcast out this URL so every device that supports bluetooth can receive it.
 
 However, we also support mDNS and uPnP over wifi. We are not limited to BLE, it is just the starter technology. We expect other ways of discovering URLs will be added over time.
 
-##Next
+## Next
 The next suggested document to read would be the technical [overview](http://github.com/google/physical-web/blob/master/documentation/technical_overview.md) document

documentation/technical_overview.md

@@ -1,30 +1,30 @@
-##Technical Overview
+## Technical Overview
 This is a prototype system being used to understand and explore the issues involved in building the Physical Web.
 
-###Broadcast
+### Broadcast
 The current design uses Bluetooth Low Energy (BLE) devices that broadcast the URL in the advertising packet. The sole job of the device is to broadcast the URL to the surrounding area. The reason is to accommodate potentially the worst-case scenario of a large number of devices in an area with many people.  A broadcast only approach avoids an N-squared problem of every user connecting to every device. By making each device broadcast constantly, any number of devices can just pick up the information passively with little conflict.
 
 This has another advantage in that it means that a user can walk through a space and leave no trace: the broadcasting devices have no idea who is listening.
 
 The current prototype broadcasts once every second, striking a balance between user response time and battery life. There is nothing stopping a device from broadcasting faster if it wishes.
 
-###BLE Format
+### BLE Format
 The URL is stored in the advertising packet of a BLE device. The packet identifies itself with a 16-bit Service UUID of 0xFEAA which indicates the beacon is an [Eddystone beacon](https://github.com/google/eddystone). Additionally, the packet sets the frame type field to 0x10 to specify that it is of the [Eddystone-URL](https://github.com/google/eddystone/tree/master/eddystone-url) format, which is designed to carry URLs.
 
 This small size of the advertising packet does not leave a lot of room for the text of the URL. This is one of tradeoffs that comes from avoiding any connections to the beacon (to reduce tracking and avoid congestion). URLs are encoded so common patterns like 'http://www.' and '.com' can be compressed into a single character. This is very similar to NDEF compression in NFC. In addition, we expect initial testers will use either short domains or a URL shortener. Both the Android and iOS apps do this automatically when a URL is typed in that is too long to fit.
 
-###Client
+### Client
 The current client is an application, rather than a system service or integrated part of the operating system, to prove out the technology. If you open the app, it lists the nearby beacons that it can see, sorted by signal strength. Note the signal strength is a very iffy metric as there many reasons why it can vary. However, if you are standing in front of device and the next device is more than five feet away, it tends to work out well in practice. This is the primary reason we include a TX_POWER byte in the advertising packet so it's possible to calculate signal loss and rank different strength beacons.
 
 The client lists the meta information from the URL: TITLE, DESCRIPTION, URL, and FAVICON. These can be pulled at the time the URL is received. Alternately, there is a simple caching proxy server that speeds up this process.
 
-###Server
+### Server
 The server receives a request from the client with all the URLs found and returns JSON listing the URLs' metadata. The current prototype collects no user data, only returning the cached information. However, alternative implementations could keep track of user choice and use that to help change the ranking within the client. The server isn't required as part of Physical Web, but it greatly simplifies the work on the client side and improves responsiveness and quality of results.
 
-###Metadata
+### Metadata
 The system expects URLs to point to a web page, which offers up the metadata described above. This somewhat limits the URLs, as they must always point to a valid HTML page. This is likely a significant limitation to URLs that want to link to native applications. This is an important use case needing further discussion. Is there an alternative way to offer this metadata but not point to a web page?
 
-###Ranking
+### Ranking
 As more devices are found, the importance of ranking the devices becomes more valuable. Sorting only by signal strength is a good start, but the server could do a much better job in two ways. The first would be to track which URLs are clicked as that implies value, so more frequently used URLs could be ranked higher. In addition, the server could track personal use, so if you tended to pick the same device at work, it might rank the device higher as well.
 
 ### Security

documentation/techpack.md

@@ -1,21 +1,21 @@
-##The Physical Web Kit 
+## The Physical Web Kit 
 If you are reading this, you’ve received one of our tech packs with several bluetooth beacons (URIBeacons) and some Intel Edison boards. This page will help you get setup.
 
 The reason for this project is to get people to try out the Physical Web, prototype something that represents a 
 real scenario and give us feedback. We’ve already received quite a bit of feedback on our github but we’re now trying to encourage more active projects. Please beat on it and let us know: either go to the issues page of our github or just send an email to [email protected].
 
-##Setting up the URIBeacons 
+## Setting up the URIBeacons 
 In order to use the beacons, you need to have the Physical Web app installed on your phone. It currently works on Android 4.4 and iOS 8 devices. Just go to their app stores, search for “Physical Web” and download the app.
 
 The beacons can be set to any URL. When you pull down the notifications tray in Android or the TodayView in iOS, you’ll see a list of nearby beacons. Picking any one will open that URL in Chrome.
 
 To change the URL you need to first go to the “Change URL” section of the app and then push the button on the beacon. This will allow you to type in a new URL. Beacons like this are clearly not secure, these are ‘testing beacons’ that are meant to be easily set for prototyping purposes.
 
-##Setting up the Edison boards
+## Setting up the Edison boards
 This document describes how to set up the Intel Edison Mini Breakout Kit and install a Physical Web HelloWorld app. The HelloWorld app, aka helloEdison will broadcast a url over Bluetooth Low Energy and mDNS. Additionally, helloEdison will connect via WebSocket to a remote server at the broadcasted url. That remote server also serves up an html client to mobile devices that navigate to the given url. The html client also connects via WebSocket to the remote server. This allows for communication to travel from helloEdison to the remote server to the html Client. The idea is that when you press the tiny white button on the Intel Edison, the helloEdison sends a message to the remote server, which then sends a message to the html client, which then indicates that the button has been pressed.
 
 
-##Assemble your Intel Edison
+## Assemble your Intel Edison
 * Open your Intel Edison Mini Breakout Kit box.
 * Remove the Intel Edison chip (it’s the smaller part and says “Intel Edison” on it).
 * Remove the Mini-Breakout board.
@@ -25,22 +25,22 @@ This document describes how to set up the Intel Edison Mini Breakout Kit and ins
 Your assembly should now look like this:
 ![Intel Edison](https://raw.githubusercontent.com/google/physical-web/master/documentation/images/IntelEdison.jpg)
 
-##Flash your Intel Edison
+## Flash your Intel Edison
 * Go to the appropriate link below depending on your computer’s operating system.
 * For Mac https://communities.intel.com/docs/DOC-23193
 * For Windows go to https://communities.intel.com/docs/DOC-23192
 * For Linux go to https://communities.intel.com/docs/DOC-23200
 * Follow the instructions to flash your Intel Edison.
 Note: The instructions on the page show the Intel Edison Arduino kit, but the same instructions apply to the Intel Edison Mini-Breakout kit. Also, please ignore the micro-switch instruction as it applies only to the Arduino kit.
 
-##Configure your Edison
+## Configure your Edison
 SSH into your Edison (using PuTTY for Windows, or terminal “screen /dev/...” command for Mac and Linux).
 To setup login, password, and wifi connection, run (and follow the onscreen instructions):
 
     configure_edison --setup
 
 
-##Update your repositories
+## Update your repositories
 To add the above repositories to the configuration file, run (copy and paste the three lines at once into the terminal):
 
     echo "src/gz all http://repo.opkg.net/edison/repo/all
@@ -56,7 +56,7 @@ To install the latest bluetooth stack, run:
     opkg install bluez5-dev
 
 
-##Install “helloEdison” project
+## Install “helloEdison” project
 Download and extract helloEdisonPackage.zip from the following url (by clicking "View Raw"):
 
 https://github.com/google/physical-web/blob/master/documentation/development_resources/helloEdisonPackage.zip
@@ -87,21 +87,21 @@ To install the node dependencies for helloEdison, run:
 
     npm install
 
-##Prepare bluetooth
+## Prepare bluetooth
 To make bluetooth ready for helloEdison (note: you’ll have to do this every time you reboot the Edison), run:
 
     rfkill unblock bluetooth
     killall bluetoothd
     hciconfig hci0 up
 
 
-##Start up helloEdison
+## Start up helloEdison
 cd into the helloEdison project folder and run:
 
     node main.js
 
 
-##Install Physical Web on your mobile device
+## Install Physical Web on your mobile device
 
 * For iOS, download and install Physical Web from the App Store
 * For Android, download and install Physical Web from the Play Store
@@ -114,6 +114,6 @@ cd into the helloEdison project folder and run:
 * The page will contain a simple graphic of a button
 
 
-##Press a button
+## Press a button
 Now press the tiny white button on the Intel Edison. As you do so, on your mobile device watch the page you just navigated to
 Every time you press the tiny white button on the Intel Edison, the button on the page on your mobile device will indicate that the button has been pressed.