First drafts for more topic overview manual entries.

src/main/resources/assets/oc2/doc/en_us/basics.md

@@ -1,3 +1,27 @@
 # Basics
+This document contains some foundational information on how [computers](block/computer.md) work. This does not necessarily mean that this information is easy reading. Basic here means the general concepts in use.
 
-TODO
+## Architecture
+Computers run on a single-core, general purpose RISC-V architecture. This means they have 64-bit registers and support floating point operations. This makes it possible to boot a modern Linux kernel on them.
+
+### Native Devices
+Native devices connected to computers are memory-mapped devices. This means they are mapped to some area in physical memory. Computers use regular Linux drivers to interact with them.
+
+What devices are available, and where those devices live, is communicated to the software running on the computer using a flattened device tree. This data structure may contain additional information on the system in general. In particular, it also stores the size of the installed [memory](item/memory.md). Since this data structure gets copied during boot, it cannot be updated later on. This is the reason computers must be rebooted when changes to native devices, such as the [network interface card](item/network_interface_card.md), are made. Devices for which this is the case will typically have a corresponding note in their tooltip.
+
+### HLAPI Devices
+The other type of device are high level API devices, sometimes also called RPC devices. These devices use a single controller which communicates with the computers via single serial device. This controller device is present in all computers, and takes care of collecting messages from multiple devices, and dispatching messages to devices. The protocol this controller uses is a simple JSON message based protocol. The `devices` Lua library provided with the default Linux library wraps around the serial device used to connect to this controller. As such, using the `devices` library whenever using a HLAPI device, such as the [redstone interface block](block/redstone_interface.md), is *strongly* recommended.
+
+Due to the nature of the employed protocol, data rate is rather limited. Most devices therefore usually only provide comparatively simple APIs which do not require sending large amounts of data either way.
+
+## Configuration
+Computers can be configured to some degree. The amount of memory, extra storage in the form of [hard drives](item/hard_drive.md) and most importantly, which cards to install, are largely up to the user. Note that the default Linux distribution does require at least 20M of memory, 24M are recommended.
+
+Most components contribute to the overall energy consumption of a computer. To conserve energy, choosing only the necessary components is essential.
+
+## Linux
+The default Linux distribution contains some basic command line tools, and the ability to write and run Lua programs. For an overview of how to interact with HLAPI devices using Lua, please see the [scripting](scripting.md) manual entry.
+
+Native devices use regular Linux drivers. For example, hard drives show up as `/dev/vdaX` devices and can be formatted and mounted regularly.
+
+Computers provide two hardware clock (RTC) devices. The first one counts time in a scale most users will think in. It is used by default, for example by command line tools like `date` and `time`. The second one measures time as it works in the world the computer runs in. To obtain the current world time, use `hwclock -f /dev/rtc1`.

src/main/resources/assets/oc2/doc/en_us/getting_started.md

@@ -1,3 +1,29 @@
 # Getting Started
+This article describes the steps required to get a [computer](block/computer.md) up and running, and gives an example of how it can be used to interact with devices.
 
-TODO
+## Building
+First things first, you need an actual computer, plus a couple of components. If you haven't already, craft these first:
+- 1x [computer](block/computer.md)
+- 1x **Linux** [hard drive](item/hard_drive.md) (regular 8M hard drive, then craft it with a [wrench](item/wrench.md))
+- 3x 8M [Memory](item/memory.md)
+
+![The basics](../img/getting_started_basics.png)
+
+Once you got all this, place down the computer. Open its inventory screen using a wrench. Alternatively, open the terminal screen, then use the toggle button to the left to switch to the inventory screen. Here, place the crafted hard drive and memory into the computer.
+
+![Computer inventory](../img/getting_started_inventory.png)
+
+## Starting
+To power up your freshly build computer, you'll usually need to supply it with some power. Have a look at the energy bar to the left of the terminal or inventory screen. Its tooltip informs you of the current amount of energy stored in the computer, and the amount of energy it requires per tick to keep running.
+
+![Computer energy info](../img/getting_started_energy.png)
+
+When you've ensured the required amount of energy is available, switch to the terminal screen and hit the power button to the top left. Alternatively use the computer while sneaking. The computer should now boot! Wait until you're prompted for a login.
+
+![Login prompt](../img/getting_started_login.png)
+
+Enter `root` as the user name to log in with and press enter. Well done, you now have a computer that's ready for use!
+
+You can now add more devices, depending on what you want to use your computer for. For information on how to control devices, have a look at the [scripting](scripting.md) manual entry.
+
+Good luck, and most importantly, have fun!

src/main/resources/assets/oc2/doc/en_us/index.md

@@ -1,8 +1,8 @@
 # The Computerists Handbook
-Hello, greetings, welcome! If you've come here, you either stumbled in by accident, are interested in building your first [computer](block/computer.md), or maybe you are looking for information on a particular [block](block/index.md) or [item](item/index.md)?
+Hello, greetings, welcome! If you've come here, you either stumbled in by accident, are interested in [building your first computer](getting_started.md), or maybe you are looking for information on a particular [block](block/index.md) or [item](item/index.md)?
 
 ## Overview
-Computers offer a variety of uses, from recreational to large-scale, highly customizable automation of other machines and devices.
+[Computers](block/computer.md) offer a variety of uses, from recreational to large-scale, highly customizable automation of other machines and devices.
 
 At the heart of each computer lies its operating system (OS). The default OS provided is a very basic Linux distribution. It offers just the most basic command line tools, as well as the means to write and run Lua programs.
 
@@ -24,4 +24,4 @@ If you're interested in a particular topic, there are some overview entries for
 - [Basics](basics.md)
 - [Scripting](scripting.md)
 - [Robotics](robotics.md)
-- [Networking](networking.md)
+- [Networking](networking.md)

src/main/resources/assets/oc2/doc/en_us/networking.md

@@ -1,3 +1,18 @@
 # Networking
+To set up a [computer](block/computer.md) network, use [network connectors](block/network_connector.md) and [network cables](item/network_cable.md) to connect the connectors. Finally, make sure a [network interface card](item/network_interface_card.md) is installed in each computer that should be part of the network.
 
-TODO
+Connectors have to be attached to any face but the front face of a computer. This allows the network card installed in it to send and receive packets through the connector.
+
+Connectors connected with cables will forward packets to each other. For more complex network setups, a [network hub](block/network_hub.md) may be necessary. It allows connecting multiple connectors with each other.
+
+## Hops
+Network packets can only travel a certain maximum number of "hops". A hop can generally be understood as a single forwarding operation. For example, a connector forwarding a packet uses one hop. A network hub forwarding a packet to each connector the packet did not arrive from uses one hop. Once the number of remaining hops reaches zero, the packet is no longer forwarded. This avoids packets going in circles forever for networks with cycles. That said, this is a safeguard mechanism. No network should contain cycles, as this will also lead to the same packet arriving multiple times on receiving computers.
+
+## Computer Setup
+To set up a computer for networking, first ensure a network card is present. After this, using the default Linux distribution, run the command `setup-network.lua`. This will provide a wizard to configure how the computer should connect to the network. Alternatively, if you know what you're doing, set up network as you would on any regular Linux installation.
+
+## DHCP
+DHCP is a protocol which allows a simplified network setup. Only one computer will need to have a statically configured network address, all other computers in the network may have their addresses assigned to them automatically. When going for this setup, ensure there is only a single computer that acts as a DHCP server. Also ensure that no computer uses a static IP address that falls into the range of dynamically distributed IP addresses.
+
+## Tools
+Once you have a network setup running, with multiple computers in one network, you have all the options in the world. For example, you can copy files between computers using `scp`, log in to a remote computer using `ssh` and write custom network programs in Lua using the `socket` library. For samples on how to use the `socket` library, please the [samples in the official repository](https://github.com/diegonehab/luasocket/tree/master/samples).

src/main/resources/assets/oc2/doc/en_us/scripting.md

@@ -1,3 +1,75 @@
 # Scripting
+Controlling devices using Lua is a core concept when using [computers](block/computer.md). Many devices are so-called high level API (HLAPI) devices. This means they are not controlled using regular Linux drives, but via a simple RPC system, employing JSON messages over a serial device.
 
-TODO
+## The Devices Library
+The default Linux distribution includes libraries to make HLAPI devices more easily accessible. The `devices` library provides utilities for discovering devices and calling methods on them, as well as obtaining documentation on devices, when available.
+
+To use the `devices` library, import it using `require("devices")`.
+
+### Methods
+`list():table` returns a list of all currently available devices. Each entry in the returned table represents a single device, including its type names and unique identifier.
+- Returns the list of connected HLAPI devices.
+
+`get(id:string):Device` returns a wrapper for a device with the specified identifier. This is similar to `find` but takes a specific identifier instead of a type name.
+- `id` is the unique identifier of the device.
+- Returns a wrapper for the specified device.
+
+`find(typeName):Device` returns a wrapper for a device of the specified type. If there are many devices of this type, it is undefined which one will be returned.
+- `typeName` is the device type for which to find a device.
+- Returns a wrapper for a device of the specified device.
+
+`methods(id:string):table` returns the list of methods offered by the device with the specified identifier. To obtain the list of methods in a more readable way, get the device wrapper and convert it to a string, instead. Also see the section on the device wrapper type.
+- `id` is the unique identifier of the device.
+- Returns the list of methods offered by the device.
+- Throws an error if obtaining the method list failed.
+
+`invoke(id:string, methodName:string, ...):any` calls the method with the specified name on the device with the specified identifier. Passes along any extra parameters. Using this method directly is not recommended. Prefer obtaining a device wrapper and invoking the method through it. Also see the section on the device wrapper type.
+- `id` is the unique identifier of the device.
+- `methodName` is the name of the method to invoke.
+- `...` are parameters to pass to the method.
+- Returns the result of the method.
+- Throws an error if invocation failed, or the method threw an exception.
+
+## The Device Wrapper
+Devices returned from the `device` library are objects of type `Device`. This is a wrapper storing the device identifier.
+
+Its main purpose is to enable seamless invocation of methods exposed by this device, as well as a convenient way to access documentation, if available.
+
+To invoke a method on such a wrapper, use colon notation, and the method's name. For example:  
+`wrapper:someMethod(1, 2, 3)`
+
+To obtain the documentation of the device, `tostring` it. In the Lua interpreter, use `=wrapper`.
+
+## Example
+For this example we will control a [redstone interface block](block/redstone_interface.md). First, place the block and connect it to the computer using [bus cables](block/bus_cable.md) and [bus interfaces](block/bus_interface.md).
+
+![Redstone interface setup](../img/scripting_redstone_interface.png)
+
+We place a redstone lamp on top of the redstone interface to have a visual indicator that our commands work.
+
+To verify the connection between device and computer, run the command `lsdev.lua` from the command line. This lists the identifiers and type names of all connected HLAPI devices. One of these should have the type `redstone` among its type names.
+
+Start Lua in interactive mode by running just `lua` from the command line.
+
+![Lua in interactive mode](../img/scripting_lua_interactive.png)
+
+Include the devices library and store it in a variable named `d`:  
+`d = require("devices")`
+
+Then get the `Device` wrapper for the redstone interface block and store it in a variable named `r`:  
+`r = d:find("redstone")`
+
+The `redstone` in this call is the device type name, the same we checked for just earlier using `lsdev.lua`.
+
+We now have a wrapper for the redstone interface block on which we may call methods. To get a list of the available methods, run `=r`.
+
+For our example, we're interested in the `setRedstoneOutput` method. It allows setting the signal emitted from the redstone interface.
+
+To light up our lamp, we want to emit a redstone signal from the top face of the redstone interface block:  
+`r:setRedstoneOutput("up", 15)`
+
+The lamp should now light up!
+
+![Lit redstone lamp](../img/scripting_lamp.png)
+
+With this, you have the tools to learn the names of connected devices, which methods they offer and how to obtain their documentation. Go ahead and experiment with the other methods of the redstone interface to read incoming redstone signals, or try out other devices!