diff --git a/cheatsheets/basics.cheatmd b/cheatsheets/basics.cheatmd new file mode 100644 index 00000000..9bd258d1 --- /dev/null +++ b/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= +``` + +#### 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= +$ mix upload nerves.local +``` + +#### Using `./upload.sh` + +```bash +$ mix firmware.gen.script + +$ export MIX_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 115200 +``` + +Exit `screen` with CTRL+A, CTRL+\ + +#### Using picocom + +```bash +$ picocom -b 115200 /dev/tty +``` + +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 + +``` +text to find +``` + +### Misc + +```elixir +iex> h Toolshed +iex> hostname +iex> top +iex> weather +iex> history +iex> hex 255 +``` diff --git a/mix.exs b/mix.exs index 35120cf5..603c8c54 100644 --- a/mix.exs +++ b/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,