Add Nerves basics cheatsheet

cheatsheets/basics.cheatmd

@@ -0,0 +1,189 @@
+# Nerves basics
+
+## Terminology
+
+| Term            | Definition                                                                                                            |
+| --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| host            | The computer on which you are editing source code, compiling, and assembling firmware                                 |
+| target          | The platform for which your firmware is built (for example, Raspberry Pi Zero W, Raspberry Pi 4, or Beaglebone Black) |
+| toolchain       | The tools required to build code for the target, such as compilers, linkers, binutils, and C runtime                  |
+| system          | A lean Buildroot-based Linux distribution that has been customized and cross-compiled for a particular target         |
+| assemble        | The process of combining system, application, and configuration into a firmware bundle                                |
+| firmware bundle | A single file that contains an assembled version of everything needed to burn firmware                                |
+| firmware image  | Built from a firmware bundle and contains the partition table, partitions, bootloader, etc.                           |
+
+## Nerves systems
+
+| Nerves system                                                                      | MIX_TARGET | Hardware                                                                         |
+| ---------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------- |
+| [nerves_system_rpi](https://github.com/nerves-project/nerves_system_rpi)           | `rpi`      | Raspberry Pi A+, B, B+                                                           |
+| [nerves_system_rpi0](https://github.com/nerves-project/nerves_system_rpi0)         | `rpi0`     | Raspberry Pi Zero and Zero W                                                     |
+| [nerves_system_rpi2](https://github.com/nerves-project/nerves_system_rpi2)         | `rpi2`     | Raspberry Pi 2                                                                   |
+| [nerves_system_rpi3a](https://github.com/nerves-project/nerves_system_rpi3a)       | `rpi3a`    | Raspberry Pi 3A and Zero 2 W                                                     |
+| [nerves_system_rpi3](https://github.com/nerves-project/nerves_system_rpi3)         | `rpi3`     | Raspberry Pi 3 B, B+                                                             |
+| [nerves_system_rpi4](https://github.com/nerves-project/nerves_system_rpi4)         | `rpi4`     | Raspberry Pi 4                                                                   |
+| [nerves_system_bbb](https://github.com/nerves-project/nerves_system_bbb)           | `bbb`      | BeagleBone Black, BeagleBone Green, BeagleBone Green Wireless, and PocketBeagle. |
+| [nerves_system_x86_64](https://github.com/nerves-project/nerves_system_x86_64)     | `x86_64`   | Generic x86_64                                                                   |
+| [nerves_system_osd32mp1](https://github.com/nerves-project/nerves_system_osd32mp1) | `osd32mp1` | OSD32MP1                                                                         |
+| [nerves_system_grisp2](https://github.com/nerves-project/nerves_system_grisp2)     | `grisp2`   | GRiSP 2                                                                          |
+
+While the Nerves core team only officially supports the above hardware, the community has added support for other boards. See [Nerves Systems on
+hex.pm](https://hex.pm/packages?search=depends:nerves_system_br).
+
+## Useful shell commands
+
+{: .col-2}
+
+### Making a new firmware from scratch
+
+#### Creating a Nerves application
+
+```bash
+$ mix nerves.new hello_nerves
+$ cd hello_nerves
+```
+
+#### Specifying Nerves target
+
+```bash
+$ export MIX_TARGET=<target>
+```
+
+#### Installing dependencies
+
+```bash
+$ mix deps.get
+```
+
+#### Building firmware
+
+```bash
+$ mix firmware
+```
+
+#### Creating a bootable SD card
+
+```bash
+$ mix burn
+```
+
+The `mix burn` command will attempt to automatically discover the SD card inserted in your host.
+
+### Uploading firmware to a Nerves device over SSH
+
+#### Using `mix upload`
+
+```bash
+$ export MIX_TARGET=<target>
+$ mix upload nerves.local
+```
+
+#### Using `./upload.sh`
+
+```bash
+$ mix firmware.gen.script
+
+$ export MIX_TARGET=<target>
+$ ./upload.sh nerves.local
+```
+
+### Connecting to the target over SSH
+
+#### Testing the network connection
+
+```bash
+$ ping nerves.local
+```
+
+#### Making the network connection
+
+```bash
+$ ssh nerves.local
+```
+
+### Connecting to the target with a serial cable
+
+#### Serial ports
+
+Nerves sends the iex prompt over a virtual serial port on the USB cable. It shows up as a device like `/dev/tty.usbmodem `or `/dev/ttyUSB0`.
+
+#### Using screen
+
+```bash
+$ screen /dev/tty<device> 115200
+```
+
+Exit `screen` with CTRL+A, CTRL+\
+
+#### Using picocom
+
+```bash
+$ picocom -b 115200 /dev/tty<device>
+```
+
+Exit `picocom` with CTRL+A, CTRL+X
+
+### Misc
+
+#### Printing Nerves information
+
+```bash
+$ mix nerves.info
+```
+
+#### Listing Nerves artifacts cached locally
+
+```bash
+$ ls ~/.nerves/artifacts
+```
+
+#### Listing Nerves downloads cached locally
+
+```bash
+$ ls ~/.nerves/dl
+```
+
+## Useful IEx commands
+
+{: .col-2}
+
+### Firmware
+
+```elixir
+iex> uname
+iex> reboot
+iex> Nerves.Runtime.revert
+iex> Nerves.Runtime.KV.get_all
+iex> NervesMOTD.print
+```
+
+### Logging
+
+```elixir
+iex> Logger.configure level: :warn
+iex> log_attach
+iex> log_detach
+```
+
+### Linux commands
+
+```elixir
+iex> cmd "ps"
+```
+
+### Reverse	search
+
+```
+<CTRL+R>text to find
+```
+
+### Misc
+
+```elixir
+iex> h Toolshed
+iex> hostname
+iex> top
+iex> weather
+iex> history
+iex> hex 255
+```

mix.exs

@@ -78,7 +78,11 @@ defmodule Nerves.MixProject do
         "docs/Customizing Systems.md",
         "docs/Experimental Features.md",
         "docs/Using the CLI.md",
-        "CHANGELOG.md"
+        "CHANGELOG.md",
+        "cheatsheets/basics.cheatmd"
+      ],
+      groups_for_extras: [
+        Cheatsheets: ~r/cheatsheets\/.?/
       ],
       source_ref: "v#{@version}",
       source_url: @source_url,