What is a Strategy?

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

bool begin(uint8_t additional_randomness = 0)

Returns true if the strategy is correctly initialized (receives a optional uint8_t used for randomness)

uint32_t back_off(uint8_t attempts)

Returns the suggested delay related to the attempts passed as parameter

bool can_start()

Returns true if the medium is free for use and false if the medium is in use by some other device

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)

Sends a string of a certain length through the medium

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

Receives a pointer where to store received information and an unsigned integer signaling 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

You can define your own set of methods to use PJON with your own strategy on the medium you prefer. If you need other custom configuration or functions, those can be defined in your Strategy class. Other communication protocols could be used inside those methods to transmit and receive data:

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

How to define a new strategy

To define the strategy you have only to create a new folder named for example YourStrategyName in 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) { ... };
};

Simply add your code in the functions declaration shown above and instantiate PJON using the strategy type you have created: PJON<YourStrategyName> bus();.


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