@@ -0,0 +1,112 @@
1++++
2+
3+title = "%loch"
4+date = "2022-02-23"
5+
6+[taxonomies]
7+grant_type = ["Proposal"]
8+grant_category = ["Core Dev"]
9+
10+[extra]
11+image = ""
12+description = "A Hardware Control Vane"
13+reward = "7 Stars"
14+assignee = ["~mopfel-winrux"]
15+champion = ["~lagrev-nocfep, ~rovnys-ricfer"]
16+grant_id = "P0244"
17+completed = false
18+canceled = false
19+
20++++
21+
22+# Introduction
23+This is a grant for a new vane called %loch. This will act as a hardware control vane providing an interface between Arvo and POSIX's IOCTL interface; enabling communication with various devices ranging from cryptographic hardware keys and dongles, embedded devices speaking on common communication interfaces (UART, SPI, I2C, etc), and IoT connected devices. POSIX-compliant host OSs provide access to these devices via file handles and through the ioctl system call. The runtime side of %loch acts as a hardware abstraction layer, which the Urbit/Hoon side complements by exposing an interface for the various expected communication types to devices
24+
25+How %loch will work is best explained with the following usecase:
26+
27+I have a receipt printer that communicates through UART communication. I want it to print out any %rumors I recieve.
28+
29+This usecase will act as an end to end test of the entire system (described below) and allow incremental experimentation until the final product.
30+
31+This grant is split into N parts
32+
33+1. Creation of the vane (%loch and loch.c)
34+2. UART communication library (/lib/uart.hoon, /mar/*)
35+3. Gall agent (%receipt)
36+4. Documentation and Tutorial
37+
38+# Vane
39+The Urbit/Hoon vane exposes an interface for registering and communicating with an external device using the host OS's systemcalls such as IOCTL. The runtime will have to be passed a list of device registrations @tas and a unix file location (e.g. [%uart '/dev/ttyUSB0'] for a uart device at ttyUSB0). When urbit is booted the runtime will pass this list of @tas to the vane to register the available devices. If a device's status changes the runtime will notify the vane of it through this same method.
40+
41+%loch will also have a list of gall agents which are subscribed to the list of devices and will notify them with changes to it.
42+
43+%loch's formal inteface is still under design but work flushing it out will fall under this grant.
44+
45+
46+# UART communication library
47+Having the %loch vane is nice but useless without "device drivers". A design decision was made to keep Arvo agnostic to different wire based communication protocols (UART, SPI, I2C, etc.). This also keeps vere agnostic to the exact communcation protocol. This design decision was made as to not flood vere with different libraries for these protocols (there is also some liscensing issues that this side steps, GPL is glitter).
48+
49+The consequences of this means that device drivers will need to be written in hoon. The driver will live in userspace and act as middleware between a gall agent and loch.
50+
51+A good basic driver to write is a UART (serial) driver.
52+
53+The driver will need to do the following:
54+
55+Define the IOCTL commands needed to read and write the UART attributes
56+Define UART marks that can convert between a UART settings struct and a noun
57+This can be as simple as a core with different settings as arms
58+Define a serialization arm that takes a noun and properly serializes it (useful for writes)
59+Define a deserialization arm that takes a noun and properly deserializes it (useful for reads)
60+Defines a read arm that handles the process of reading N bytes and unpacks it
61+Defines a write arm that handles the process of writing a noun to the device
62+This driver will act as an example driver that an application can use to talk to a UART device using loch.
63+
64+
65+# Gall Agent
66+Once the vane and library is tested work will begin on implementing a gall agent that subscribes to the %rumors app by ~paldev. The app will begin by subscribing to device notifications from %loch. It will then allow the user to pick which device they want to talk to (device metadata is outside the scope of this proposal). It will register itself to the device on %loch and set it up with the correct settings (baudrate, parity etc.). It will subscribe to %rumors and on recieving one it will send the correct command for the printer to output it.
67+
68+The Agent will include a simple web interface that will allow the user to
69+
70+Pick the device
71+Start subscribing to rumors
72+Stop subscribing to rumors
73+
74+
75+# Documentation and Tutorial
76+Documentation of how the vane works is vital to the succuss of it. The benefit of having a working app alongside the vane is to show users how to use the vane. The resulting communication library and gall agent will be written into a tutorial that should allow anyone to write a gall agent that can speak UART.
77+
78+The library will also act as a template to expand %loch to other devices.
79+
80+
81+# Milestones
82+
83+## Milestone 1: Vane
84+Payment: 3 Stars
85+
86+This milestone includes a working vane that we can "bitbang" commands to talk to an arbitrary IOCTL device.
87+
88+
89+## Milestone 2: UART Library
90+Payment: 2 stars
91+
92+This milestone is complete when a user can execute simple read/write across a UART wire without any "bitbanging"
93+
94+
95+## Milestone 3: Gall Agent
96+Payment: 1 star
97+
98+This milestone is complete when a user can install the app and have the printer print its rumors
99+
100+
101+## Milestone 4: Documentation and Tutorial
102+Payment: 1 star
103+
104+This milestone is complete with the delivery of a documentation and tutorial package.
105+
106+
107+
108+
109+
110+Additional Documents can be found:
111+
112+https://github.com/Native-Planet/documents/tree/main/proposal/loch