Plasma – Modules Guide

Introduction

In Plasma, devices do not have any innate logic encoded into them. You must add a Controller component in order to create a sketch, and drag in other components of the device as sketch nodes to connect them together.

But have you noticed that you can actually add more than one Controller to a device? Indeed, if you do so, you lose the ability to edit the sketch by pressing Q on a non-Controller, but that is because there is now more than one sketch!

Since each Controller hosts its own sketch, it’s possible for each one to perform its own duty. But what if you want them to work together?

What if:

• You have a set of related components, for example the four wheels on a vehicle, along with the four motors and two (or four) steering servos. You want to control them all as a group, without cluttering up your main sketch!
• Or, you have a bunch of sketch code you’d like to use on multiple devices, but you can’t copy and paste nodes from one sketch to another!
• Or, you’d like multiple Controllers on one device to communicate data for any reason!

If any of those sound like you… well, modules may just be the solution!

What Are Modules?

Normally, a Controller is pretty basic as a component. If you bring it into your sketch, you only get controls for stopping, starting, and resetting its sketch.

However, a Controller can also be a module, in which case it has extra properties, commands, and outputs, anything you want!

In that case, the ports of the module get forwarded to the sketch inside of its Controller, allowing you to encapsulate all sorts of logic into a node. This node can be used from another Controller on your device, allowing the two to communicate!

How to Create a Module

First, open the sketch view of the Controller that you’d like to turn into a module.

On the top-left of the sketch view, there are some buttons, like Minimap, Label, Variables… you’re looking for the “Interface” button.

This button will allow you to open the interface manager, which will initially be empty.

You can click the “New” button at the bottom-left to add ports to the interface.

Port Types

“Ports” is the official term used to refer to the inputs and outputs of a node — wires connect ports of nodes, not the nodes themselves. There are three types of ports that can be used:

1. Command ports. A command port is a type of port that accepts an update, an instantaneous signal that carries no value but causes something to happen. Commands can also accept values, in which case they trigger every time the value is outputted (whether it changes or not), although only the update itself is passed through. Command ports are positioned along the top-left of a node. Some examples of commands are:
   • The “Evaluate” command of a math expression.
   • The “Call” command of a Lua function.
   • The “Reset Sketch” command of a Controller
2. Property ports. A property port is a type of port that can receive values through wires, and values can also be assigned to it manually from the sketch view. A property port remembers the last value it was sent, and also propagates updates sent through it even when the value does not change. A property port can be configured to accept any value or only values of a certain type. Property ports are positioned below command and output ports.
3. Output ports. An output port is a type of port that can transmit values through wires. An output port remembers the last value that it sent, and can transmit updates even when the value does not change. Output ports are positioned along the top-right of a node.

How to Access Your Ports

While inside a module, three nodes can be used to interact with the ports that have been defined:

1. The Command Interfacer, which allows you to receive commands sent to a command port on your module.

Commands only flow from outside the module inwards, so they are placed inside the module, and then triggered by another controller, which will propagate into any Command Interfacers that have their Command property set to the right port.

2. The Property Interfacer, which allows you to retrieve the value of a property port on your module, as well as receive updates sent through it (such as when the value changes, but not necessarily).

Properties also flow from outside the module inwards, except they can propagate values as well as updates.

3. The Output Interfacer, which allows you to send values and updates through an output port on your module.

This instead flows from inside the module outwards, transferring both values and updates, like the inverse of a property.

That’s about it! All a module is, is a Controller with a defined interface, whose sketch uses the interface to perform its function. Whether that is receiving data from outside, transmitting data from sensors, or doing something else, all it needs to be a module is to have that interface.

Publishing Modules to the Workshop

Plasma actually has a dedicated category for modules, or at least, devices containing modules that people can integrate into their own devices! All you have to do is tick this “Save as Module” box when saving your device:

Then, when you share it on the Workshop, it will be specially marked as a module, showing this icon:

That way, others will be able to find it easily and know that it’s a module!