chore(docs): describe OT2 architecture (#6245)

This is a quick attempt to describe things that might as an outsider have helped me to understand how my OT2 works. The text is clumsy in many ways and I'm sure not comprehensive, but I thought I'd submit the PR on the basis that something is better than nothing, and as a starting point for improvement. I won't be at all offended if you don't agree and want to hold off on this until you have time to sit down and do it properly.

I think things can be quite opaque e.g. "what does the robot server do?" (#6164 (comment)) and that signposting users to the code that is more likely to be relevant to them (API, then buildroot and robot server) as opposed to not (protocol designer, labware designer, etc.) could be helpful.

Intended to fix (in part) #4375.

Co-authored-by: Max Marrone <[email protected]>
Co-authored-by: Theo <[email protected]>

OT2_ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# OT-2 Architecture
+
+## Hardware
+
+### Raspberry Pi
+
+Inside the OT-2 is a small computer (a [Raspberry Pi 3 Model B](https://www.raspberrypi.org/products/raspberry-pi-3-model-b/)), running Linux.
+
+Data is stored on the Raspberry Pi's SD card. The majority of the filesystem is read-only but certain directories such as `/data/` and `/var/` allow read-write access. The OT-2 camera (a webcam) is connected to a USB port on the Raspberry Pi (this port, and a 4th port which may have a flash drive that's no longer used, are normally covered by the Pi's case).
+
+#### Networking
+
+Your computer communicates with the Raspberry Pi inside the OT-2 via a network connection.
+
+When you connect to your robot via USB, you're actually connecting to the Raspberry Pi's Ethernet port. The USB socket on the side of the robot leads to an internal USB-to-Ethernet adapter, which in turn leads to the Pi's Ethernet port.
+
+When you connect your computer to the robot's USB port, your computer recognizes the device as a new network interface, and establishes a [link-local](https://en.wikipedia.org/wiki/Link-local_address) connection to the OT-2.
+
+(You can also connect the OT-2 to a Wi-Fi network.)
+
+### Lights, switches
+
+The Raspberry Pi controls the lights of the robot, and detects presses on the switch and opening of the door via its General Purpose Input-Output (GPIO) ports. The GPIO ports also allow the Raspberry Pi to reset the motor controller board (described below).
+
+### Motor control
+
+The robot has 6 axes of motion, each controlled by a stepper motor:
+
+- X: left/right
+- Y: forward/back
+- Z: left pipette up/down
+- A: right pipette up/down
+- B: left pipette plunger
+- C: right pipette plunger
+
+The motors, endstops, and probing switches are connected to the motor controller board, housed in the gantry. The motor controller board is a modified [Smoothieboard](http://smoothieware.org/smoothieboard) running [a custom fork of Smoothieware](https://github.com/Opentrons/SmoothiewareOT).
+
+The motor controller board is connected to the Raspberry Pi via a UART connection, with the Pi sending commands in [G-code](https://en.wikipedia.org/wiki/G-code).
+
+## Software
+
+The main operating system of the robot is a minimal version of Linux built using [a custom fork of buildroot](https://github.com/Opentrons/buildroot).
+
+The buildroot [configuration](https://github.com/Opentrons/buildroot/blob/opentrons-develop/configs/ot2_defconfig) includes a number of standard packages, and also some specific to the OT2. Those specific to the OT2 are: the API, the robot server, the 'shared data', and the update server.
+
+### API
+
+The [Opentrons API](https://github.com/Opentrons/opentrons/tree/edge/api) is a Python package that provides an interface to control the OT-2. Protocols are written in the protocol API, which is a part of the API package.
+
+With the API alone, a Python script or Jupyter notebook running on the OT2 is able to control the robot to perform liquid-handling operations.
+
+### Robot server
+
+The main such Python programme is the [robot server](https://github.com/Opentrons/opentrons/tree/edge/robot-server), which provides the interface to the robot that the Opentrons app on a user's computer can access to do routine robot work. It provides endpoints that allow performing calibration and running protocols uploaded from the app.
+
+Note that only one process can have access to the robot's GPIO ports at a time. By default the robot server connects to these ports on start-up, which prevents a copy of the API running in Jupyter or imported from a Python script from using GPIO functionality. To gain access to the GPIOs in these custom scripts, one can disable the robot server with `systemctl stop opentrons-robot-server`, before importing the Opentrons API into the other Python script. However this will prevent the Opentrons app from connecting to the robot until the robot server is restarted with `systemctl start opentrons-robot-server`, or the robot is rebooted.
+
+### Shared data
+
+Some data needs to be shared between different parts of the Opentrons codebase. For example, the descriptions of how labware is shaped are needed by both Protocol Designer and the robot itself.
+
+We keep data like this in the special [shared-data](https://github.com/Opentrons/opentrons/tree/edge/shared-data) directory, so all those different parts can easily include it.
+
+## Update server
+
+The [update server](https://github.com/Opentrons/opentrons/tree/edge/update-server) is a separate server designed primarily to allow updating the robot's software with a new system image built using buildroot. The update server also controls some system-specific tasks such as handling SSH keys and setting the robot's name.