|
|
@@ -0,0 +1,88 @@
|
|
|
+# External API
|
|
|
+
|
|
|
+## Description
|
|
|
+
|
|
|
+This package provides an API interface to external applications by providing a raw byte-based API.
|
|
|
+
|
|
|
+## Running
|
|
|
+
|
|
|
+In order to run this, first start the main HOLEG application. This means starting the `Main` class
|
|
|
+file, either by running this file inside the IDE or creating and running the jar version. Then use the algorithm option
|
|
|
+to load the handheld class in order to run the server.
|
|
|
+
|
|
|
+## API
|
|
|
+
|
|
|
+The protocol operates on binary level. The data types are interpreted based on their expected
|
|
|
+usage. It contains no type information is always fixed in length.
|
|
|
+
|
|
|
+### Data types
|
|
|
+
|
|
|
+| Name | Size (bytes) | Encodes | Notes |
|
|
|
+| ---- | --- | --- | --- |
|
|
|
+| Byte | 4 | two complement | signed |
|
|
|
+| Int | 4 | two complement | signed |
|
|
|
+| Bool | 4 | false as 0x0, true otherwise | boolean |
|
|
|
+| Float | 4 | IEEE 754 | - |
|
|
|
+| String | Variable | UTF-8 | Length is given by a two byte unsigned length prefix |
|
|
|
+| `Array<Type>` | Variable | Directly concatenated | List of elements, length is given a preceding field |
|
|
|
+
|
|
|
+Messages types are identified by their respective ID in `Byte`. A message
|
|
|
+is always prefixed by this ID. You can see an example below for `SetAmount`. The documented
|
|
|
+messages show the ID numbers in their respective titles (`SetAmount(10)` - `10` is the ID).
|
|
|
+
|
|
|
+| Type (byte) | Index | Amount |
|
|
|
+| --- | --- | --- |
|
|
|
+| 10 | Int | Int |
|
|
|
+
|
|
|
+### Input (Client -> Server)
|
|
|
+
|
|
|
+#### SetAmount(10)
|
|
|
+
|
|
|
+Set amount of devices.
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Index | Int | Holon element index |
|
|
|
+| Amount | Int | Target amount
|
|
|
+
|
|
|
+#### SetEnable(11)
|
|
|
+
|
|
|
+Enable or disable a holon element.
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Index | Int | Holon element index
|
|
|
+| Enabled | Bool | Target state |
|
|
|
+
|
|
|
+#### IncreaseAmount(12)
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Index | Int | Holon element index |
|
|
|
+
|
|
|
+#### DecreaseAmount(13)
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Index | Int | Holon element index |
|
|
|
+
|
|
|
+### Output (Server -> Client)
|
|
|
+
|
|
|
+#### Update(20)
|
|
|
+
|
|
|
+Once sent on initial connection and then updated if there are any changes. Updates
|
|
|
+contain the **complete** current view.
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Size | Int | Length of the following array |
|
|
|
+| Amount | `Array<HolonElement>` | Current state of each Holon element
|
|
|
+
|
|
|
+Holon Element
|
|
|
+
|
|
|
+| Field Name | Type | Notes |
|
|
|
+| --- | --- | --- |
|
|
|
+| Name | String | User defined name i.e. Fridge, TV |
|
|
|
+| Amount | Int | Number of devices of this type |
|
|
|
+| Energy | Float | Energy usage per device |
|
|
|
+| Enabled | Bool | If the device is enabled |
|
