Metadata-Version: 2.1
Name: swarmnet
Version: 0.0.7
Summary: A gossip-based swarm communication library
Home-page: https://github.com/tgodfrey0/SwarmNet
Author: Toby Godfrey
Author-email: swarmnet@tgodfrey.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# SwarmNet

A robust communications library for robot swarms. This is based on gossip protocols where the message will propagate around the swarm. When an agent receives a message it has not seen before, it will broadcast it to all other members of the swarm. 

## Usage

A `SwarmNet` object must be created that handles all of the communication. Only one instance should be created. To start the communication framework, the `start()` method must be run.

**All devices must use the same port number**

This `start()` command will broadcast a JOIN command to register with the rest of the swarm. 

## Message Parsers

Parsers are defined to handle incoming messages of specific types, for example, you may want to send `COUNT 1` to increase a distributed counter by 1 when the `COUNT` command is received. This would be defined as follows.

```python

counter = 0

def count_recv(msg: Optional[str]) -> None:
  counter += int(msg)

sn = SwarmNet({"COUNT": count_recv})
sn.start()

while(True):
  pass

sn.kill()

```

*It is important to remember that the parser functions are called from a different thread. Special care should be taken to ensure data integrity and consistency across threads.*

The type of each parser is `Optional[str] -> None` where the string is a string of any fields in the message. For example, if the message is `CMD field1 field2`, the string will be `"field1 field2`.

If a message is received with a command token for which there is no parser, an error message is produced with a list of recognised command tokens. To prevent error spam in more complex systems, you can set certain commands to be ignored by defining the parser as `None`. For example, if the above code was deployed in a swarm that also had `DEBUG` messages that were only important to one specific node, you could ignore them using `None`.

```python

counter = 0

def count_recv(msg: Optional[str]) -> None:
  counter += int(msg)

sn = SwarmNet({"COUNT": count_recv, "DEBUG": None})
sn.start()

while(True):
  pass

sn.kill()

```

## Message Format

All messages follow the format: `<CMD> <DATA1> <DATA2> ...`

A dictionary that maps command tokens to functions is passed to the `SwarmNet` constructor. The signature of this map is `Dict[str, Optional[Callable[[Optional[str]], None]]]` where the `str` passed to the parser function is the rest of the message string (if any)

Internally, every message is prefixed with an identifier that is not overwritten when the message is forwarded by receivers. This means agents will not parse their own message or parse the same message more than once.

