From 41c56c1126ec2a0603c87537e2d8e6945835e680 Mon Sep 17 00:00:00 2001
From: Jan Keromnes <janx@linux.com>
Date: Fri, 6 Dec 2019 15:17:02 +0000
Subject: [PATCH] [doc] Document Arduino Pro IDE extension and a few services

---
 README.md                       |  3 ++
 arduino-ide-extension/README.md | 52 +++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 arduino-ide-extension/README.md

diff --git a/README.md b/README.md
index 529d8ebc..d45803ed 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,9 @@ Then you can start the browser example again:
 yarn --cwd browser-app start
 ```
 
+Click [here](./arduino-ide-extension/README.md) for more details on various IDE services, and the Arduino Pro IDE implementation in general.
+
+
 ## Arduino Pro IDE Electron Application
 The project is built on [Azure DevOps](https://dev.azure.com/typefox/Arduino).
 
diff --git a/arduino-ide-extension/README.md b/arduino-ide-extension/README.md
new file mode 100644
index 00000000..d32e2543
--- /dev/null
+++ b/arduino-ide-extension/README.md
@@ -0,0 +1,52 @@
+## Arduino IDE Extension
+
+Arduino Pro IDE is based on Theia, and most of its IDE features, UIs and customizations are implemented in this Theia extension.
+
+### IDE Services
+
+IDE services typically have a backend part (usually in [src/node/](./src/node/)) and a front-end part (usually in [src/browser/](./src/browser/)).
+
+#### Boards Service
+
+The Boards Service continuously checks the computer's ports, in order to detect when you connect or disconnect an Arduino board.
+
+The Boards Manager lists all the known board types, and allows downloading new cores to get additional board types.
+
+- [src/common/protocol/boards-service.ts](./src/common/protocol/boards-service.ts) implements the common classes and interfaces
+- [src/node/boards-service-impl.ts](./src/node/boards-service-impl.ts) implements the service backend:
+  - discovering ports & boards
+  - searching for compatible board types
+  - installing new board types
+- [src/browser/boards/boards-list-widget.ts](./src/browser/boards/boards-service-client-impl.ts) implements the Boards Manager front-end:
+  - browsing/searching available board types
+  - installing new board types
+
+#### Core Service
+
+The Core Service is responsible for building your sketches and uploading them to a board.
+
+- [src/common/protocol/core-service.ts](./src/common/protocol/core-service.ts) implements the common classes and interfaces
+- [src/node/core-service-impl.ts](./src/node/core-service-impl.ts) implements the service backend:
+  - compiling a sketch for a selected board type
+  - uploading a sketch to a connected board
+
+### Monitor Service
+
+The Monitor Service allows getting information back from sketches running on your Arduino boards.
+
+- [src/common/protocol/monitor-service.ts](./src/common/protocol/monitor-service.ts) implements the common classes and interfaces
+- [src/node/monitor-service-impl.ts](./src/node/monitor-service-impl.ts) implements the service backend:
+  - connecting to / disconnecting from a board
+  - receiving and sending data
+- [src/browser/monitor/monitor-widget.tsx](./src/browser/monitor/monitor-widget.tsx) implements the serial monitor front-end:
+  - viewing the output from a connected board
+  - entering data to send to the board
+
+#### Config Service
+
+The Config Service knows about your system, like for example the default sketch locations.
+
+- [src/common/protocol/config-service.ts](./src/common/protocol/config-service.ts) implements the common classes and interfaces
+- [src/node/config-service-impl.ts](./src/node/config-service-impl.ts) implements the service backend:
+  - getting the `arduino-cli` version and configuration
+  - checking whether a file is in a data or sketch directory