From eff203cf11c606156ecc702011982a8ce0b70671 Mon Sep 17 00:00:00 2001
From: Derek Kraan <derek.kraan@gmail.com>
Date: Mon, 21 Aug 2017 15:23:52 +0200
Subject: [PATCH] Update docs for clarity (h/t @jschneck on Slack)

[@fhunleth - removed :nerves_network from extra_applications]
---
 OLD_NERVES_RUNTIME.md | 31 +++++++++++++++++++
 README.md             | 71 +++++++++++--------------------------------
 2 files changed, 49 insertions(+), 53 deletions(-)
 create mode 100644 OLD_NERVES_RUNTIME.md

diff --git a/OLD_NERVES_RUNTIME.md b/OLD_NERVES_RUNTIME.md
new file mode 100644
index 0000000..c23ba86
--- /dev/null
+++ b/OLD_NERVES_RUNTIME.md
@@ -0,0 +1,31 @@
+## Loading WiFi kernel module (unnecessary for newer versions of `nerves_runtime`)
+
+**Note**
+If you are using `nerves_runtime` >= `0.3.0` the kernel module will be auto
+loaded by default, and this step is not necessary.
+
+Before WiFi will work, you will need to load any modules for your device if they
+aren't loaded already. Here's an example for Raspberry Pi 0 and Raspberry Pi 3:
+
+``` elixir
+defmodule MyApplication do
+  use Application
+
+  def start(_type, _args) do
+    import Supervisor.Spec, warn: false
+
+    children = [
+      worker(Task, [fn -> init_kernel_modules() end], restart: :transient, id: Nerves.Init.KernelModules)
+    ]
+
+    opts = [strategy: :one_for_one, name: MyApplication.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+
+  def init_kernel_modules() do
+    {_, 0} = System.cmd("modprobe", ["brcmfmac"])
+  end
+end
+
+```
+
diff --git a/README.md b/README.md
index 9b6f6b8..42a9142 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,12 @@ def deps(target) do
   [ system(target),
     {:nerves_network, "~> 0.3"}
   ]
+end
 ```
 
 # WiFi Networking
 
-## Installation
+## Installation & Setup
 
 You'll first need to set the regulatory domain in your `config.exs` to your ISO
 3166-1 alpha-2 country code. In theory this is optional, but you'll get the
@@ -29,37 +30,22 @@ config :nerves_network,
   regulatory_domain: "US"
 ```
 
-## Setup
-
-**Note**
-If you are using `nerves_runtime` >= `0.3.0` the kernel module will be auto
-loaded by default, and this step is not necessary.
-
-Before WiFi will work, you will need to load any modules for your device if they
-aren't loaded already. Here's an example for Raspberry Pi 0 and Raspberry Pi 3:
-
-``` elixir
-defmodule MyApplication do
-  use Application
-
-  def start(_type, _args) do
-    import Supervisor.Spec, warn: false
-
-    children = [
-      worker(Task, [fn -> init_kernel_modules() end], restart: :transient, id: Nerves.Init.KernelModules)
-    ]
-
-    opts = [strategy: :one_for_one, name: MyApplication.Supervisor]
-    Supervisor.start_link(children, opts)
-  end
-
-  def init_kernel_modules() do
-    {_, 0} = System.cmd("modprobe", ["brcmfmac"])
-  end
-end
+The easiest way to get up and running is by statically setting your WiFi (and possibly ethernet) configuration in `config.exs`:
 
+```elixir
+config :nerves_network, :default,
+  wlan0: [
+    ssid: System.get_env("NERVES_NETWORK_SSID"),
+    psk: System.get_env("NERVES_NETWORK_PSK"),
+    key_mgmt: String.to_atom(key_mgmt)
+  ],
+  eth0: [
+    ipv4_address_method: :dhcp
+  ]
 ```
 
+If you are using an older version (`< 0.3.0`) of `nerves_runtime` then you'll need to do some additional setup to load the correct kernel module for WiFi. See [this page](OLD_NERVES_RUNTIME.md) for more information.
+
 ## Scanning
 
 You can scan by running:
@@ -81,7 +67,7 @@ iex> Nerves.Network.scan "wlan0"
    level: -43, noise: 0, qual: 0, ssid: "dlink", tsf: 580587711245}]
 ```
 
-## Running
+## Runtime WiFi network setup
 
 Setup your network connection by running:
 
@@ -115,13 +101,9 @@ Nerves.Network.setup "eth0", ipv4_address_method: :static,
 Nerves.Network.setup "usb0", ipv4_address_method: :linklocal
 ```
 
-# Configuring Defaults
+# Using `nerves_network` with `bootloader`
 
-`nerves_network` allows default network interface settings to be set using
-application configuration. This can be helpful when using `nerves_network` with
-[`bootloader`](https://github.com/nerves-project/bootloader).
-
-Configuring `bootloader` to start `nerves_network`:
+Set default network interface settings as described above. Then you can use [`bootloader`](https://github.com/nerves-project/bootloader) to start `nerves_network`:
 
 ```elixir
 config :bootloader,
@@ -129,23 +111,6 @@ config :bootloader,
   app: :your_app
 ```
 
-The following example will pull WiFi network settings from the system
-environment variables and configure the interface's IP address using DHCP:
-
-```elixir
-key_mgmt = System.get_env("NERVES_NETWORK_KEY_MGMT") || "WPA-PSK"
-
-config :nerves_network, :default,
-  wlan0: [
-    ssid: System.get_env("NERVES_NETWORK_SSID"),
-    psk: System.get_env("NERVES_NETWORK_PSK"),
-    key_mgmt: String.to_atom(key_mgmt)
-  ],
-  eth0: [
-    ipv4_address_method: :dhcp
-  ]
-```
-
 ## Limitations
 
 Currently, only IPv4 is supported. The library is incredibly verbose in its