Brief Introduction

In NetLink parlance, a Station is currently defined as an ObjectReference that a) can be connected to a workshop power grid and which b) has the NetLink:LinkLayer (or compatible) script attached to it. A small settlement network of NetLink Stations might therefore look like this:


Any Station on the power grid depicted above can communicate with any other Station on that power grid. The only limitation is that the wireless segment requires power for transmission. Wired and snapped Stations otoh are technically capable of communicating across unpowered (data-only) links.

Before you ask: Yes, it's possible to create compatible LinkLayer scripts that are not dependent on a Workshop Power Grid. Such a script variant could instead use, say, an In-Game Radio Station or whatever else as the "physical" Layer for the network. But I have not done this yet. I intend to.


Station Addressing Modes

NetLink supports multiple schemes to address Stations on the local network: Loopback (send to Self), Unicast (send to a specific Station), Broadcast (send to all connected Stations) and Multicast (send to a list of specific Stations) are well known from the real world. When delivering Frames, NetLink further behaves exactly like real-world switched Ethernet: Unicast Frames on the local network are delivered solely to the intended destination, with a fallback to Broadcast mode for unknown (non-local) destinations only. This is in steep contrast to "classic" Ethernet before Network Switches were a thing, eg the Thicknet/Thinnet era of early Ethernet and -later- of Ethernet HUBs. Back then, all Frames were always broadcasted to everyone on the network.

Translated to the in-game scenario, NetLink's built-in switching capabilities result in minimal script load and allow for very large networks: Participating Stations are not regularly forced to receive (and then dismiss) network traffic that doesn't concern them.



Multicast mode works only slightly different to IRL: Instead of sending Frames through a Multicast group on a Network Switch first, a NetLink Station can directly deliver payloads to a user specified subset of other Stations on the local network.

There is an additional addressing mode called Directcast, which is a NetLink specific concept that doesn't exist as such in real world Ethernet. And even so, it is a rather esoteric mode, useful nonetheless for objects that rely on snapped power connections. The reach of a Directcast is limited to immediate neighbors; That is, Stations that have a direct connection with the Sender. And "direct connection" has a very strict meaning here: Two objects connected by a single wire are considered directly connected, as are two objects snapped together. Objects wired through any intermediary object, say a Power Pylon, are however not directly connected. Wireless objects have a direct connection only to the radiator(s) they're drawing power from, but to nothing else.

NetLink communication is stateless and all network transmissions are offloaded, not to hardware like IRL but to native code: It is lightweight and fast. And while the similarities between NetLink and Ethernet extend into even more intricate, technical detail, there are some stark differences as well.


Similar, But Different (From The Real World)

The most apparent dissimilarity is that NetLink needs no special Network Switches, as every Station simply acts as it's own Network Switch. This is possible because the "physical" Layer (The Workshop Power Grid) used by NetLink in your Game has properties vastly different from any actual physical Layer you'd ever encounter in the real world (such as Ethernet's famous Twisted Pair cabling). Thereof results the slight difference in Multicast operation. And it's for the same reason that wireless NetLink doesn't need any WLAN Access Points: Every powered object with radiation range (ie, the vanilla "Connector" piece) naturally acts as an Access Point to every wireless NetLink Station within the radiation range.

The Network Engineers among you will be especially pleased to learn that NetLink doesn't have a so called Maximum Transmission Unit (MTU) either. In the Game, you can transfer arbitrary amounts of data -subject to limits imposed by the game environment itself- within a single NetLink Frame. I guess you could even say that from an NPC's Point of View, the bandwidth of a single NetLink Frame transmission appears to be infinite. And there's never any collisions or runt Frames on a NetLink wire either.

Ah, such are the benefits of operating within a simulation!


Basic Unit Of Telecommunication: The Frame

Frames have been mentioned often. And in fact, a NetLink Frame's structure looks eerily similar to that of an 802.1Q Ethernet Frame. Oi, but what's this "Frame" thing then, in the context of Ethernet, you ask? The simple answer: It's like a Packet, but on Layer 2!



In case this didn't make much sense: Think of a Frame as an envelope, wrapped around the data to be transmitted (the Payload) - As one would wrap an envelope around a letter, to transmit it through the postal service system. And just like you'd write an address onto the envelope before sending it, the Frame is imprinted with additional information pertaining to the communication process, before it is sent out to the network.

Destination and Source fields are pretty self explanatory but where Ethernet passes MAC addresses, NetLink will pass ObjectReferences here. The LNET Tag field is reserved for future expansion. The FrameType field determines the type of upper level protocol that handles the data in the Payload field; For example, the GCP protocol described below uses FrameType 10. As there is no real-life physical Layer involved in transmission, the CRC/Frame Check Sequence is omitted from NetLink Frames. Instead, there is a preceding version identifier in the NetLink Frame, which has no analogy in Ethernet.



The Frame is used by the network to deliver the payload to it's intended recipient(s), like the postal service uses the the envelope to figure out the recipient's address. It is important to note that the Payload (ie the Letter) can contain anything the user wants, and the network does not know any specifics about the nature of said Payload. Neither does it care: All that is relevant to the network itself, is actually contained in the other fields of the Frame.


Network Stack

Now, the upper level protocol that runs on top of NetLink - It does not care about entire NetLink Frames. Only about FrameType and Payload fields.

As outgoing Data (Payload) from a sender's upper level protocol is handed down to NetLink via the various LinkSend() functions, NetLink will create a new Frame and will encapsulate the Payload into the Frame's Payload field. The sender's upper level protocol also specifies Destination and FrameType of a transmission. Next, the Frame is transmitted by NetLink, over the network connection, to the Destination(s).

The intended Station receives the Frame and will check if there is an upper level Protocol registered for the FrameType of the incoming Frame. If there is not, the receiving Station will discard the Frame. If there however is, the Station will de-encapsulate the Payload from the Frame and pass the Payload up to the registered upper level protocol(s), through NetLink's OnLinkReceive function call. 

This kind of layered communications architecture is very common IRL and it is known as a network- or protocol stack:



As you might have guessed by looking at the above diagram, the "stack" part comes from things being layered on top of each other:

* At the base, there is the Workshop Power Grid - The so called Physical Layer (PHY), or Layer 1.
* NetLink uses the Workshop Power Grid and provides Frame based communication across that power grid - The Link Layer (LNK), or Layer 2.
* On top of that, there can be other, higher level Protocols such as The Group Control Protocol (GCP) - The Network Layer (NET), or Layer 3.
* Not depicted above, but it's possible to stack more protocols on top of Layer 3 - The Transport Layer (TRN), or Layer 4.
* Finally, the topmost layer is the Application that does something with the protocols below it - The Application Layer (APP), or Layer 5.

Some among you will recognize the very much intended similarity to The Internet's DoD Stack. In fact, as you're surfing the Interwebs, you are using a protocol stack. And what's good for the goose is good for the gander.

The beauty of all this layering stuff is that upper Layers need not know nor care about the internal specifics of lower Layers, and vice versa.

Included with NetLink is a Layer 3 protocol called "Group Control Protocol" or "GCP" for short, which builds on NetLink to provide functionality similar to that of popular X-10 Home Automation systems. GCP's purpose is networked ON/OFF-control of user defined sets of devices. GCP can operate in Peer-To-Peer mode, or have it's groups managed by centralized controllers. Each group is identified by a name you can specify, and supports up to 127 channels. Each channel in a group can be either ON or OFF and could control, say, a lamp. There are 3 commands defined in GCP protocol, to control channels with: ON, OFF and TOGGLE. These commands could be sent out by, say, a button. Like so.



If the button sends a TOGGLE command to group "DEFAULTGROUP" on channel 1, every lamp that is on that same group and channel will toggle it's ON/OFF state upon receiving the command. Should the button send an ON command to "MYGROUP" on channel 2, every lamp configured for "MYGROUP" channel 2 will turn ON. If an OFF command is sent to "MYGROUP" channel 2, every lamp on that group and channel will turn OFF instead. In this way, you can control any number of lamps from any number of buttons, without having to run any wires. Different Group Channels will not interfere with each other. So it's very easy to set up per-room lighting in any number of buildings: Just give each building a group name and each room in a building gets at least one channel number.