diff --git a/doc/Concepts.md b/doc/Concepts.md new file mode 100644 index 0000000..eac4d04 --- /dev/null +++ b/doc/Concepts.md @@ -0,0 +1,97 @@ +Use this if you want to know how the OS works. + +# Network + +Every computer has a id assigned by the mod. It is a unique number that identifies the computer and cannot be changed. +The native implementation of the network stack works with channels. If you listen on a channel you will receive all messages sent to that channel. +Every computer listens to the channel with its id and a brodcast channel. +The broadcast channel is used for Routing Tables and GPS packets. + +Network messages can be forwarded by other computers. This is done by the Routing Table. The routing algorithm prefers wire over wireless connections. + +Packages also have a time-to-live (TTL) value. This is used to prevent packages from being forwarded forever. You will get a response if a package is dropped because of TTL. + +There is also a concept of protocols. A protocol is used to distinguish between different types of packages. +A protocol is basically a string and that is used to forward packages to the correct handler. You can use `registerProto` to listen for packages with a specific protocol. + +There are 2 ways of sending messages to other computers: `sendAndAwait` and `sendAndForget`. +`sendAndAwait` will wait for a response from the remote computer and return it. +`sendAndForget` will send the message and return immediately and does not care about the response. +You can compare it to UDP and TCP. + +## Usage + +```haxe +import net.Net; + +var data = {"foo": "bar"}; + +Net.instance.sendAndAwait(netID,"protoname",data).map((response)->{ + switch (response){ + case Success(data): + trace(data); + case Failure(error): + trace(error); + } +}); + +Net.instance.registerProto("res",(pack: GenericPackage)->{ + var requestPack: Package = cast pack; // Try not to use Dynamic + + requestPack.respond("Hello Back"); +}); + +``` + +# Peripherals + +Peripherals are devices that are connected to the computer. They can be used to interact with the world. +Every peripheral has an address and a type. The address can be "back" or "right" to refer to the peripheral on the back or right side of the computer or +something like "energyCell_0" to refer to something connected via cable. Peripherals can be accessed via the Peripheral class. + +Also peripherals can be made accessible via the network. More on that later. + +## Usage + +```haxe +var back = Peripheral.instance.getRedstone("back"); +back.setOutput(true); + +var drive Peripheral.instance.getDrive("drive_0"); +drive.eject(); +``` + +# GUI + +If you want to write something to the screen you have to create a `WindowContext` via the `WindowManager`. This allows programs to write to the screen without interfering with each other. + +There are currently 2 types of `WindowContext`: the `BufferedVirtualTermWriter` that stores the state of the screen in a buffer and prints it to the screen +when it is activeted and the `StatelessVirtualTermWriter` which calls a render method when it is activated. Currently i prefer the `StatelessVirtualTermWriter` because its not so heavy on the RAM but both work. + +They both can be used just like the [nativ implmentation](https://tweaked.cc/module/term.html). + +## Usage + +```haxe +var ctx = WindowManager.instance.createNewBufferedContext(); +ctx.setCursorPos(0, 0); +ctx.setCursorBlink(false); +ctx.setBackgroundColor(Blue); +ctx.setForegroundColor(White); +ctx.write("Hello world!"); +``` + +# Proceses + +The concept of processes tryes to encapsulate programs. A process is basically an interface with the `run(handle: ProcessHandle)` method. +The idea is that you can register all you disposable resources in the handle and they will be disposed when the process is killed or crashes. + +A process can be used as a command on the terminal or as a service. See [bin/HelloWorld.hx](../src/bin/HelloWorld.hx) for an example. +Basically everything that runs and is not part of the kernel is a process. + +In order for you program to be used it needs to be registered in the `BinStore` and the `DCEHack` manually. + +# EndOfLoop + +You can imagine the whole runtime like the event loop is JS. The `EndOfLoop` class is used to register callbacks that are called at the end of the loop. +This is like the `setTimeout(0, callback)` in JS. diff --git a/doc/Manual.md b/doc/Manual.md new file mode 100644 index 0000000..66d23be --- /dev/null +++ b/doc/Manual.md @@ -0,0 +1,112 @@ +Use this if you want to know how to use the OS. + +# Commands + +## Disk + +Interact with a disk drive. + +Synopsys: + +- `disk ls` list all disk drives and its content +- `disk play ` play an audio disk inside a disk drive +- `disk stop ` stops playing audio +- `disk eject ` ejects the disk +- `disk lable [lable]` Reads or sets a lable on a disk. + +## GPS + +Interact with the buildin GPS and INS (Inertial Navigation System) system. The INS is used to update a turtle's position when it is moving. + +The GPS has 4 states of accuracy: + +- `0` Unknown position +- `1` Position from INS or its best guess +- `2` Position from manual input or the last known position +- `3` Position from GPS + +In case of a turtle the GPS accuracy will be set to `1`. + +Synopsys: + +- `gps set ` set the position manually. This will get saved. +- `gps status` prints the current GPS accuracy, position and INS status. +- `gps locate` try to locate the current position. Accuracy will be set to `3` if successful. +- `gps ins` perform an INS alignment. Used to get the current heading. + +## KSettings + +Get and set Kernel settings. + +Current settings are: + +- `hostname` the hostname of the computer +- `sitecontroller` the id of the site controller + +Synopsys: + +- `ks get ` print the value of a setting +- `ks set ` set the value of a setting +- `ks list` list all settings + +## LSPS + +List all processes running on the computer. Very simple and not very useful other than for debugging. + +## Net + +Interact with the network stack. + +Synopsys: + +- `net route` print the routing table +- `net iface` list all network interfaces +- `net proto` list all network currently active protocols +- `net ping ` ping a remote computer by id + +## Peripherals + +Interact with the peripherals connected to the computer. + +Synopsys: + +- `perf inspect ` print all types and methods of a peripheral +- `perf list` list all peripherals + +## Redstone + +Interact with the redstone. Support for Project Red's Bundle Cable is partialy implemented. + +Synopsys: + +- `rs on ` turn on redstone on a side +- `rs off ` turn off redstone on a side +- `rs get ` get the redstone state on a side + +## Service + +Interact with the service manager. A service is a program that runs in the background and can be automatically started when the computer boots. + +A service is a normal program. In order to create a new service you must register a command with arguments under a name. +After that you can start the service by its name. If it is running you can enable it so it will be started when the computer boots. + +Synopsys: + +- `srv start ` start a service +- `srv stop ` stop a service +- `srv register [args...]` register a service +- `srv unregister ` unregister a service +- `srv list` list all services +- `srv enable ` enable a service. Must be started before it can be enabled. + +## Turtle + +Interact with a turtle. Very simple. More to come maybe. + +Synopsys: +- `turtle forward` move the turtle forward +- `turtle back` move the turtle back +- `turtle up` move the turtle up +- `turtle down` move the turtle down +- `turtle left` turn the turtle left +- `turtle right` turn the turtle right