move stuff and add docs

config/host/dev.exs

@@ -15,7 +15,7 @@ config :farmbot, :init, [
 
 # Transports.
 config :farmbot, :transport, [
-  Farmbot.BotState.Transport.GenMQTT
+  # Farmbot.BotState.Transport.GenMQTT
 ]
 
 

lib/farmbot/firmware.ex

@@ -3,14 +3,34 @@ defmodule Farmbot.Firmware do
 
   use GenStage
   require Logger
+  
+  defmodule Handler do
+    @moduledoc """
+    Any module that implements this behaviour should be a GenStage.
 
+    The implementng stage should communicate with the various Farmbot
+    hardware such as motors and encoders. The `Farmbot.Firmware` module
+    will subscribe_to: the implementing handler. Events should be
+    Gcodes as parsed by `Farmbot.Firmware.Gcode.Parser`.
+    """
+    
+    @doc "Start a firmware handler."
+    @callback start_link :: GenServer.on_start
+
+    @doc "Write a gcode."
+    @callback write(Farmbot.Firmware.Gcode.t) :: :ok | {:error, term}
+  end
+  
   @handler Application.get_env(:farmbot, :behaviour)[:firmware_handler] || raise "No fw handler."
 
   @doc "Start the firmware services."
-  def start_link(opts) do
-    GenStage.start_link(__MODULE__, [], opts)
+  def start_link do
+    GenStage.start_link(__MODULE__, [], [name: __MODULE__])
   end
 
+  @doc "Writes a Gcode to a the running hand:ler"
+  def write(code), do: @handler.write(code)
+
   def init([]) do
     {:producer_consumer, [], subscribe_to: [@handler]}
   end
@@ -34,8 +54,8 @@ defmodule Farmbot.Firmware do
     {:location_data, %{position: %{x: x, y: y, z: z}}}
   end
 
-  def handle_gcode(_code) do
-    # Logger.warn "unhandled code: #{inspect code}"
+  def handle_gcode(code) do
+    Logger.warn "unhandled code: #{inspect code}"
     nil
   end
 end

lib/farmbot/firmware/gcode.ex

@@ -0,0 +1,8 @@
+defmodule Farmbot.Firmware.Gcode do
+  @moduledoc """
+  Gcode is the itermediate representation
+  of commands to the underlying hardware.  
+  """
+  @typedoc "Code representation." 
+  @type t :: term
+end

lib/farmbot/firmware/gcode/parser.ex

@@ -1,6 +1,6 @@
 defmodule Farmbot.Firmware.Gcode.Parser do
   @moduledoc """
-    Parses farmbot_arduino_firmware G-Codes.
+  Parses farmbot_arduino_firmware G-Codes.
   """
 
   require Logger

lib/farmbot/firmware/stub_handler.ex

@@ -3,14 +3,15 @@ defmodule Farmbot.Firmware.StubHandler do
   use GenStage
   require Logger
 
-  @doc "Start the firmware handler stub."
-  def start_link(opts) do
+  @behaviour Farmbot.Firmware.Handler
+
+  def start_link do
     Logger.warn("Firmware is being stubbed.")
-    GenStage.start_link(__MODULE__, [], opts)
+    GenStage.start_link(__MODULE__, [], [name: __MODULE__])
   end
 
-  def write(handler, string) do
-    GenStage.call(handler, {:write, string})
+  def write(code) do
+    GenStage.call(__MODULE__, {:write, code})
   end
 
   def init([]) do

lib/farmbot/firmware/supervisor.ex

@@ -12,8 +12,8 @@ defmodule Farmbot.Firmware.Supervisor do
   def init([]) do
     handler_mod = Application.get_env(:farmbot, :behaviour)[:firmware_handler] || raise @error_msg
     children = [
-      worker(handler_mod, [[name: handler_mod]]),
-      worker(Farmbot.Firmware, [[name: Farmbot.Firmware]])
+      worker(handler_mod, []),
+      worker(Farmbot.Firmware, [])
     ]
     opts = [strategy: :one_for_one]
     supervise(children, opts)

lib/farmbot/firmware/uart_handler.ex

@@ -10,13 +10,13 @@ defmodule Farmbot.Firmware.UartHandler do
   @doc """
   Writes a string to the uart line
   """
-  def write(handler, string) do
-    GenStage.call(handler, {:write, string}, :infinity)
+  def write(code) do
+    GenStage.call(__MODULE__, {:write, code}, :infinity)
   end
 
   @doc "Starts a UART Firmware Handler."
-  def start_link(opts) do
-    GenStage.start_link(__MODULE__, [], opts)
+  def start_link do
+    GenStage.start_link(__MODULE__, [], [name: __MODULE__])
   end
 
   ## Private
@@ -30,11 +30,13 @@ defmodule Farmbot.Firmware.UartHandler do
   end
 
   def init([]) do
+    # If in dev environment, it is expected that this be done at compile time.
+    # If ini target environment, this should be done by `Farmbot.Firmware.AutoDetector`. 
     tty = Application.get_env(:farmbot, :uart_handler)[:tty] || raise "Please configure uart handler!"
     {:ok, nerves} = UART.start_link()
     Process.link(nerves)
     case open_tty(nerves, tty) do
-      :ok -> {:producer, %State{nerves: nerves, codes: []}}
+      :ok -> {:producer, %State{nerves: nerves, codes: []}}  
       err -> {:stop, err, :no_state}
     end
   end
@@ -57,10 +59,13 @@ defmodule Farmbot.Firmware.UartHandler do
       rx_framing_timeout: 500)
   end
 
+  # if there is an error, we assume something bad has happened, and we probably
+  # Are better off crashing here, and being restarted.
   def handle_info({:nerves_uart, _, {:error, reason}}, state) do
     {:stop, {:error, reason}, state}
   end
 
+  # Unhandled gcodes just get ignored.
   def handle_info({:nerves_uart, _, {:unhandled_gcode, _code_str}}, state) do
     {:noreply, [], state}
   end
@@ -70,8 +75,8 @@ defmodule Farmbot.Firmware.UartHandler do
   end
 
   def handle_call({:write, stuff}, _from, state) do
-    UART.write(state.nerves, stuff)
-    {:reply, :ok, [], state}
+    r = UART.write(state.nerves, stuff)
+    {:reply, r, [], state}
   end
 
   def handle_demand(_amnt, state) do

lib/farmbot/firmware/uart_handler/auto_detector.ex

@@ -1,4 +1,4 @@
-defmodule Farmbot.Firmwre.UartHandler.AutoDetector do
+defmodule Farmbot.Firmware.UartHandler.AutoDetector do
   @moduledoc "Helper for autodetecting and configuring a UART fw device."
 
 end