What is a Strategy?

A strategy is an abstraction layer used to physically transmit data. Thanks to the strategies PJON can operate transparently on a wide range of media and protocols. Take a look at the strategies video introduction for a brief showcase of their features.

Strategy Physical layer Protocol Pins needed
SoftwareBitBang Electrical impulses over conductive element PJDL 1 or 2
AnalogSampling Light pulses over air or optic fiber PJDLS 1 or 2
EthernetTCP Electrical/radio impulses over wire/air TCP Ethernet port
LocalUDP Electrical/radio impulses over wire/air UDP Ethernet port
GlobalUDP Electrical/radio impulses over wire/air UDP Ethernet port
DualUDP Electrical/radio impulses over wire/air UDP Ethernet port
OverSampling Electrical/radio impulses over wire/air PJDLR 1 or 2
ThroughSerial Electrical/radio impulses over wire/air TSDL 1 or 2
ThroughSerialAsync Electrical/radio impulses over wire/air TSDL 1 or 2
ThroughLoRa Radio impulses over air LoRa 3 or 4
ESPNOW Radio impulses over air ESPNOW WiFi link
Any Virtual inheritance, any of the above Any of the above Any of the above

A Strategy is a class containing a set of methods used to physically send and receive data along with the required getters to handle retransmission and collision:

bool begin(uint8_t additional_randomness = 0)

Receives an optional parameter of type uint8_t used for randomness and returns true if the strategy is correctly initialized.

uint32_t back_off(uint8_t attempts)

receives a paramenter of type uint8_t and returns the suggested delay for a given number of attempts.

bool can_start()

Returns true if the medium is free for use and false if the medium is busy.

void handle_collision()

Handles a collision.

uint8_t get_max_attempts()

Returns the maximum number of attempts in case of failed transmission.

void send_string(uint8_t *string, uint16_t length)

Receives a pointer to a string and its length and sends it through the medium. The sending procedure must be blocking.

uint16_t receive_string(uint8_t *string, uint16_t max_length) { ... };

Receives a pointer where to store received information and an unsigned integer signalling the maximum string length. It should return the number of bytes received or PJON_FAIL.

void send_response(uint8_t response) { ... };

Send a response to the packet's transmitter.

uint16_t receive_response() { ... };

Receives a response from the packet's receiver.

// Simple Serial data link layer implementation example
void send_response(uint8_t response) {
  Serial.print(response);
};

Above it is demonstrated how simply other communication protocols can be used to define a new custom strategy.

How to define a new strategy

To define the strategy it is required to create a new folder named for example YourStrategyName in the strategies directory and write the necessary file YourStrategyName.h:

class YourStrategyName {
  public:
    uint32_t back_off(uint8_t attempts) { ... };
    bool     begin(uint8_t additional_randomness) { ... };
    bool     can_start() { ... };
    uint8_t  get_max_attempts() { ... };
    uint16_t receive_string(uint8_t *string, uint16_t max_length) { ... };
    uint16_t receive_response() { ... };
    void     send_response(uint8_t response) { ... };
    void     send_string(uint8_t *string, uint16_t length) { ... };
};

The last thing to do is to add the inclusion of the new strategy in PJON_Strategies.h. If all is correct it should be possible to instantiate PJON using the new strategy:

PJON<YourStrategyName> bus(44);
// Use PJON as always

Strategy related methods required for configuration can be defined within the strategy. For example the SoftwareBitBang strategy uses a dedicated setter for the communication pin:

bus.strategy.set_pin(12);

This document is automatically generated from the github repository. If you have noticed an error or an inconsistency, please report it opening an issue here

Strategies abstraction

PJON codebase uses strategies to physically communicate through the medium used, abstracting the data link layer from its procedure. A Strategy is a class containing the back-off configuration and a set of methods able to send and receive messages; 7 strategies are available to communicate data through various media. Take a look at the strategies video introduction for a brief showcase of their features.

STRATEGIES

The PJON protocol handbook

This is the first publication about PJON, it contains the documentation, the specification, many application examples and troubleshooting techniques. The book is made in Italy and within its 216 pages the whole PJON network protocol stack and its strategies are accurately described with graphs and color pictures. If you are interested in the PJON protocol and you would like a printed copy, pre-order an early version personally signed by Giovanni Blu Mitolo filling in the form below: