Add example project

Author: mattludwigs

example/.formatter.exs

@@ -0,0 +1,8 @@
+# Used by "mix format"
+[
+  inputs: [
+    "{mix,.formatter}.exs",
+    "{config,lib,test}/**/*.{ex,exs}",
+    "rootfs_overlay/etc/iex.exs"
+  ]
+]

example/.gitignore

@@ -0,0 +1,17 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump

example/README.md

@@ -0,0 +1,61 @@
+# Example
+
+Example of driving GPIOs via the character device driver.
+
+This example provides switching between two LEDs via a button. When the button
+is not press `:led1` will be active and when the button is pressed `:led2` will
+be active.
+
+By default this will try to use `gpiochip0` for the GPIO device. `:led1` will be
+set to line `17` and `:led2` will be set to line `22`. The button events will be
+sent to line `27`. This defaults should work for Raspberry PI based systems.
+However, if you need to configure the system you can in the `target.exs` file
+like:
+
+```elixir
+config :example,
+  config: [
+    chip: <chip_name>,
+    led1: <led1_line_number>
+    led2: <led2_line_number>,
+    button: <button_line_number>
+  ]
+```
+
+![Circuit Example rpi0](assets/cdev_example_rpi0.png)
+
+## Notes
+
+In the latest Nerves system the character device driver will not work, so this
+example ensures that we use the `1.13` series systems to make sure the Linux
+headers support the GPIO character driver. Once the Nerves systems update to a
+capable Linux header version this project will be updated.
+
+## Targets
+
+Nerves applications produce images for hardware targets based on the
+`MIX_TARGET` environment variable. If `MIX_TARGET` is unset, `mix` builds an
+image that runs on the host (e.g., your laptop). This is useful for executing
+logic tests, running utilities, and debugging. Other targets are represented by
+a short name like `rpi3` that maps to a Nerves system image for that platform.
+All of this logic is in the generated `mix.exs` and may be customized. For more
+information about targets see:
+
+https://hexdocs.pm/nerves/targets.html#content
+
+## Getting Started
+
+To start your Nerves app:
+  * `export MIX_TARGET=my_target` or prefix every command with
+    `MIX_TARGET=my_target`. For example, `MIX_TARGET=rpi3`
+  * Install dependencies with `mix deps.get`
+  * Create firmware with `mix firmware`
+  * Burn to an SD card with `mix firmware.burn`
+
+## Learn more
+
+  * Official docs: https://hexdocs.pm/nerves/getting-started.html
+  * Official website: https://nerves-project.org/
+  * Forum: https://elixirforum.com/c/nerves-forum
+  * Discussion Slack elixir-lang #nerves ([Invite](https://elixir-slackin.herokuapp.com/))
+  * Source: https://github.com/nerves-project/nerves

example/assets/cdev_example_rpi0.png

@@ -0,0 +1,33 @@
+# This file is responsible for configuring your application
+# and its dependencies with the aid of the Mix.Config module.
+#
+# This configuration file is loaded before any dependency and
+# is restricted to this project.
+import Config
+
+# Enable the Nerves integration with Mix
+Application.start(:nerves_bootstrap)
+
+config :example, target: Mix.target()
+
+# Customize non-Elixir parts of the firmware. See
+# https://hexdocs.pm/nerves/advanced-configuration.html for details.
+
+config :nerves, :firmware, rootfs_overlay: "rootfs_overlay"
+
+# Set the SOURCE_DATE_EPOCH date for reproducible builds.
+# See https://reproducible-builds.org/docs/source-date-epoch/ for more information
+
+config :nerves, source_date_epoch: "1615393459"
+
+# Use Ringlogger as the logger backend and remove :console.
+# See https://hexdocs.pm/ring_logger/readme.html for more information on
+# configuring ring_logger.
+
+config :logger, backends: [RingLogger]
+
+if Mix.target() == :host or Mix.target() == :"" do
+  import_config "host.exs"
+else
+  import_config "target.exs"
+end

example/config/config.exs

@@ -0,0 +1,3 @@
+import Config
+
+# Add configuration that is only needed when running on the host here.

example/config/host.exs

@@ -0,0 +1,100 @@
+import Config
+
+# Use shoehorn to start the main application. See the shoehorn
+# docs for separating out critical OTP applications such as those
+# involved with firmware updates.
+
+config :shoehorn,
+  init: [:nerves_runtime, :nerves_pack],
+  app: Mix.Project.config()[:app]
+
+# Nerves Runtime can enumerate hardware devices and send notifications via
+# SystemRegistry. This slows down startup and not many programs make use of
+# this feature.
+
+config :nerves_runtime, :kernel, use_system_registry: false
+
+# Erlinit can be configured without a rootfs_overlay. See
+# https://github.com/nerves-project/erlinit/ for more information on
+# configuring erlinit.
+
+config :nerves,
+  erlinit: [
+    hostname_pattern: "nerves-%s"
+  ]
+
+# Configure the device for SSH IEx prompt access and firmware updates
+#
+# * See https://hexdocs.pm/nerves_ssh/readme.html for general SSH configuration
+# * See https://hexdocs.pm/ssh_subsystem_fwup/readme.html for firmware updates
+
+keys =
+  [
+    Path.join([System.user_home!(), ".ssh", "id_rsa.pub"]),
+    Path.join([System.user_home!(), ".ssh", "id_ecdsa.pub"]),
+    Path.join([System.user_home!(), ".ssh", "id_ed25519.pub"])
+  ]
+  |> Enum.filter(&File.exists?/1)
+
+if keys == [],
+  do:
+    Mix.raise("""
+    No SSH public keys found in ~/.ssh. An ssh authorized key is needed to
+    log into the Nerves device and update firmware on it using ssh.
+    See your project's config.exs for this error message.
+    """)
+
+config :nerves_ssh,
+  authorized_keys: Enum.map(keys, &File.read!/1)
+
+# Configure the network using vintage_net
+# See https://github.com/nerves-networking/vintage_net for more information
+config :vintage_net,
+  regulatory_domain: "US",
+  config: [
+    {"usb0", %{type: VintageNetDirect}},
+    {"eth0",
+     %{
+       type: VintageNetEthernet,
+       ipv4: %{method: :dhcp}
+     }},
+    {"wlan0", %{type: VintageNetWiFi}}
+  ]
+
+config :mdns_lite,
+  # The `host` key specifies what hostnames mdns_lite advertises.  `:hostname`
+  # advertises the device's hostname.local. For the official Nerves systems, this
+  # is "nerves-<4 digit serial#>.local".  mdns_lite also advertises
+  # "nerves.local" for convenience. If more than one Nerves device is on the
+  # network, delete "nerves" from the list.
+
+  host: [:hostname, "nerves"],
+  ttl: 120,
+
+  # Advertise the following services over mDNS.
+  services: [
+    %{
+      name: "SSH Remote Login Protocol",
+      protocol: "ssh",
+      transport: "tcp",
+      port: 22
+    },
+    %{
+      name: "Secure File Transfer Protocol over SSH",
+      protocol: "sftp-ssh",
+      transport: "tcp",
+      port: 22
+    },
+    %{
+      name: "Erlang Port Mapper Daemon",
+      protocol: "epmd",
+      transport: "tcp",
+      port: 4369
+    }
+  ]
+
+# Import target specific config. This must remain at the bottom
+# of this file so it overrides the configuration defined above.
+# Uncomment to use target specific configurations
+
+# import_config "#{Mix.target()}.exs"

example/config/target.exs

@@ -0,0 +1,41 @@
+defmodule Example do
+  @moduledoc false
+
+  use GenServer
+
+  alias Circuits.GPIO.Chip
+
+  def start_link(args) do
+    GenServer.start_link(__MODULE__, args)
+  end
+
+  @impl GenServer
+  def init(args) do
+    chip = Keyword.get(args, :chip, "gpiochip0")
+    led1 = Keyword.get(args, :led1, 17)
+    led2 = Keyword.get(args, :led2, 22)
+    button = Keyword.get(args, :button, 27)
+
+    {:ok, line} = Chip.request_lines(chip, [led1, led2], :output)
+
+    # Set initial values led1 will be on and led2 will be off
+    :ok = Chip.set_values(line, [1, 0])
+
+    :ok = Chip.listen_event("gpiochip0", button)
+
+    {:ok, line}
+  end
+
+  @impl GenServer
+  def handle_info({:circuits_cdev, 27, _timestamp, 1}, line) do
+    Chip.set_values(line, [0, 1])
+
+    {:noreply, line}
+  end
+
+  def handle_info({:circuits_cdev, 27, _timestamp, 0}, line) do
+    Chip.set_values(line, [1, 0])
+
+    {:noreply, line}
+  end
+end

example/lib/example.ex

@@ -0,0 +1,43 @@
+defmodule Example.Application do
+  # See https://hexdocs.pm/elixir/Application.html
+  # for more information on OTP Applications
+  @moduledoc false
+
+  use Application
+
+  def start(_type, _args) do
+    # See https://hexdocs.pm/elixir/Supervisor.html
+    # for other strategies and supported options
+    opts = [strategy: :one_for_one, name: Example.Supervisor]
+
+    children =
+      [
+        # Children for all targets
+        # Starts a worker by calling: Example.Worker.start_link(arg)
+        # {Example.Worker, arg},
+      ] ++ children(target())
+
+    Supervisor.start_link(children, opts)
+  end
+
+  # List all child processes to be supervised
+  def children(:host) do
+    [
+      # Children that only run on the host
+      # Starts a worker by calling: Example.Worker.start_link(arg)
+      # {Example.Worker, arg},
+    ]
+  end
+
+  def children(_target) do
+    example_args = Application.get_env(:example, :config, [])
+
+    [
+      {Example, example_args}
+    ]
+  end
+
+  def target() do
+    Application.get_env(:example, :target)
+  end
+end

example/lib/example/application.ex

@@ -0,0 +1,68 @@
+defmodule Example.MixProject do
+  use Mix.Project
+
+  @app :example
+  @version "0.1.0"
+  @all_targets [:rpi, :rpi0, :rpi2, :rpi3, :rpi3a, :rpi4, :bbb, :osd32mp1, :x86_64]
+
+  def project do
+    [
+      app: @app,
+      version: @version,
+      elixir: "~> 1.9",
+      archives: [nerves_bootstrap: "~> 1.10"],
+      start_permanent: Mix.env() == :prod,
+      build_embedded: true,
+      deps: deps(),
+      releases: [{@app, release()}],
+      preferred_cli_target: [run: :host, test: :host]
+    ]
+  end
+
+  # Run "mix help compile.app" to learn about applications.
+  def application do
+    [
+      mod: {Example.Application, []},
+      extra_applications: [:logger, :runtime_tools]
+    ]
+  end
+
+  # Run "mix help deps" to learn about dependencies.
+  defp deps do
+    [
+      # Dependencies for all targets
+      {:nerves, "~> 1.7.0", runtime: false},
+      {:shoehorn, "~> 0.7.0"},
+      {:ring_logger, "~> 0.8.1"},
+      {:toolshed, "~> 0.2.13"},
+
+      # Dependencies for all targets except :host
+      {:nerves_runtime, "~> 0.11.3", targets: @all_targets},
+      {:nerves_pack, "~> 0.4.0", targets: @all_targets},
+      {:circuits_cdev, path: "../", targets: @all_targets},
+
+      # Dependencies for specific targets
+      {:nerves_system_rpi, "~> 1.13.0", runtime: false, targets: :rpi},
+      {:nerves_system_rpi0, "~> 1.13.0", runtime: false, targets: :rpi0},
+      {:nerves_system_rpi2, "~> 1.13.0", runtime: false, targets: :rpi2},
+      {:nerves_system_rpi3, "~> 1.13.0", runtime: false, targets: :rpi3},
+      {:nerves_system_rpi3a, "~> 1.13.0", runtime: false, targets: :rpi3a},
+      {:nerves_system_rpi4, "~> 1.13.0", runtime: false, targets: :rpi4},
+      {:nerves_system_bbb, "~> 2.8.3", runtime: false, targets: :bbb},
+      {:nerves_system_osd32mp1, "~> 0.4", runtime: false, targets: :osd32mp1},
+      {:nerves_system_x86_64, "~> 1.13.0", runtime: false, targets: :x86_64}
+    ]
+  end
+
+  def release do
+    [
+      overwrite: true,
+      # Erlang distribution is not started automatically.
+      # See https://hexdocs.pm/nerves_pack/readme.html#erlang-distribution
+      cookie: "#{@app}_cookie",
+      include_erts: &Nerves.Release.erts/0,
+      steps: [&Nerves.Release.init/1, :assemble],
+      strip_beams: Mix.env() == :prod or [keep: ["Docs"]]
+    ]
+  end
+end