Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update devicenet doc #29

Merged
merged 1 commit into from
Sep 21, 2023
Merged

Update devicenet doc #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 62 additions & 23 deletions src/en/space-station-14/device-network.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Device Network

Device networking allows machines and devices to communicate with each other while adhering to restrictions like range or being connected to the same powernet. Players will also have the abillity to interact with the device network in multiple ways. For example one could use a packet sniffer in his pda *(Not yet implemented)* to listen to messages sent over the wireless device network.
Device networking allows machines and devices to communicate with each other while adhering to restrictions like range or being connected to the same powernet. Players will also have the abillity to interact with the device network in multiple ways. For example one could use a packet sniffer in their pda *(Not yet implemented)* to listen to messages sent over the wireless device network.

## Quick Overview
Entities can join a network and will be assigned a network address. These entities can then optionally choose to listen on some frequency. Any device on a network can send packets on any frequency (not just one it's listening on). The packets can either be broadcast, or directed at a specific address. The actual packets take the form of ECS events. A system just needs to listen for a `DeviceNetworkPacketEvent`. This event contains information about the sender and a `NetworkPayload`, which is basically just a `Dictionary<string, object>`. The contents of the payload and how to interpret them is just hard coded in each system. Some commonly used string keys are defined in `DeviceNetworkConstants.cs`.

### Network ids:
Device Net Ids are used to segregate devices into different sub networks that **can't** interact with eachother. This is done for performance and organisational reasons and to prevent players from interacting with packets that are not supposed to be interacted with.
Device Net Ids are used to segregate devices into different sub networks. This is done for performance and organisational reasons and to prevent players from interacting with packets that are not supposed to be interacted with.

```admonish warning
Device net ids **do not** specify how a device connects to other devices (e.g wireless). Use the components for that.
Expand All @@ -24,10 +24,13 @@ Device net ids **do not** specify how a device connects to other devices (e.g wi
**3 - ApcNet `netId: Apc`**
Used for wired networks that are limited to apc extension cables. E.g. light switches. This is supposed to be used with the `ApcNetworkComponent` if the device doesn't use a custom device net id.

**4 - AtmosDevices `netId: AtmosDevices`**
Used for atmospherics devices like scrubbers to segregate them from other networks


## Network Connection Components
To use the device network you need to add the DeviceNetworkComponent and the component for the type of connection you want. You can also not use one of the connection components when you want the device to always be able to send and receive messages.
Currently there are three types of network connections: Wired, APC and Wireless.
There are different types of connection components.
### Device Network Component
This is the required component for sending and receiving device network messages.

Expand Down Expand Up @@ -151,6 +154,42 @@ components:
- type: WiredNetworkComponent
```

</details>

### Station Limited Network Component

Allows devices that belong to the same station to send and receive packets to each other.

<details>
<summary>YAML</summary>

```yaml=
components:
- type: DeviceNetworkComponent
...
- type: StationLimitedNetwork
allowNonStationPackets: <bool>
```

**allowNonStationPackets**
Allows the device to receive packets from devices that don't have a `StationLimitedNetwork` component.

</details>

### Device Network Requires Power Component

Prevents any packets from being received if the device doesn't have power.

<details>
<summary>YAML</summary>

```yaml=
components:
- type: DeviceNetworkComponent
...
- type: DeviceNetworkRequiresPower
```

</details>

## The device network system
Expand Down Expand Up @@ -225,7 +264,7 @@ This event is raised before a device network message is sent. Subscribed to by o
<details>
<summary>DETAILS</summary>

``QueuePacket(EntityUid uid, string? address, NetworkPayload data, uint? frequency = null)``
``QueuePacket(EntityUid uid, string? address, NetworkPayload data, uint? frequency = null, int? network = null, DeviceNetworkComponent? device = null)``

**uid**
The EntityUid of the sending entity.
Expand All @@ -238,6 +277,9 @@ This event is raised before a device network message is sent. Subscribed to by o

**frequency**
The frequency on which to send the data. If null, will default to the devices current transmit frequency.

**network**
The network id to send on.
</details>

The device network system contains more public methods for things like setting the listening frequency of a device.
Expand All @@ -262,15 +304,12 @@ The class DeviceNetworkConstants contains common network ids and string constant

When creating network payloads you should try to use constants for keys and values that are always the same.

One example of a command and message is the mailing units `NET_CMD_REQUEST` for querying other units and its `NET_TAG` message for responding with its tag. *(currently not implemented)*
One example of a command and message is the mailing units `get_mailer_tag` for querying other units and its `mailer_tag` message for responding with its tag.

### Standard payload constants:

**COMMAND**
The key used for specifying the command/type of payload e.g. PDA_MAIL.

## Device Network Configuration
*TODO: Explain device network configuration and device lists*
The key used for specifying the command/type of payload e.g. pda_mail.

## Examples:
### Sending a network Message
Expand All @@ -279,19 +318,19 @@ One example of a command and message is the mailing units `NET_CMD_REQUEST` for
//This is somewhere at the top of your entity system
[Dependency] private readonly DeviceNetworkSystem _deviceNetworkSystem = default!;

public const string NET_CMD_PDA_MAIL = "pda_mail";
public const string NET_TARGET_MAIL = "target_mail_address";
public const string NET_SENDER_MAIL = "sender_mail_address";
public const string NET_MESSAGE = "message";
public const string NetCmdPdaMail = "pda_mail";
public const string NetTargetMail = "target_mail_address";
public const string NetSenderMail = "sender_mail_address";
public const string NetMessage = "message";
...
//When you want to send a network message you need to construct a network payload and send it using theDeviceNetworkSystems QueuePacket method.
//When you want to send a network message you need to construct a network payload and send it using the DeviceNetworkSystems QueuePacket method.
var payload = new NetworkPayload
{
[DeviceNetworkConstants.COMMAND] = NET_CMD_PDA_MAIL,
[DeviceNetworkConstants.COMMAND] = NetCmdPdaMail,
//You're not restricted to using DeviceNetworkConstants.COMMAND
[NET_MESSAGE] = "Hi Bob, bla bla bla...",
[NET_TARGET_MAIL] = "[email protected]",
[NET_SENDER_MAIL] = "[email protected]"
[NetMessage] = "Hi Bob, bla bla bla...",
[NetTargetMail] = "[email protected]",
[NetSenderMail] = "[email protected]"
};

_deviceNetworkSystem.QueuePacket(uuidOfCurrentEntity, addressOfMailserverOrSomething, payload);
Expand All @@ -304,8 +343,8 @@ The sending entity should either be pre-configured to send on the mailing freque
...
[Dependency] private readonly DeviceNetworkSystem _deviceNetworkSystem = default!;

public const string NET_CMD_PING = "ping"
public const string NET_MESSAGE = "message";
public const string NetCmdPing = "ping"
public const string NetMessage = "message";

public override void Initialize()
{
Expand All @@ -319,18 +358,18 @@ public override void Initialize()

private void OnPacketReceived(EntityUid uid, DeviceNetworkComponent component, DeviceNetworkPacketEvent args)
{
//Since we are doing it the recomendet way of using the command constant we try to get it from the payload
//Since we are doing it the recommended way of using the command constant we try to get it from the payload
if (args.Data.TryGetValue(DeviceNetworkConstants.COMMAND, out String command))
{
//If that command is the PING command (you can check for your own command here)
if (command == NET_CMD_PING)
if (command == NetCmdPing)
{
//We create a payload containing the ping_response command and "Hello World" as a message.
//(For this example I just passed the command name as a string instead of creating a constant.)
var payload = new NetworkPayload
{
[DeviceNetworkConstants.COMMAND] "ping_response",
[NET_MESSAGE] = "Hello World"
[NetMessage] = "Hello World"
};

//And send the response to that ping
Expand Down