Configuration

PJON uses predefined constants, setters and getters to support features and constraints configuration.

Buffers configuration

Before including the library it is possible to define the length of its buffers defining the PJON_MAX_PACKETS and PJON_PACKET_MAX_LENGTH constants:

  #define PJON_MAX_PACKETS 1
  #define PJON_PACKET_MAX_LENGTH 20
  /* PJON can dispatch up to 1 packet with a payload
     of up to 20 bytes - packet overhead (5-35 bytes) */

Strategy configuration

Strategies are classes that abstract the physical transmission of data. PJON uses strategies as template parameters although since version 13.0 that complexity is hidden behind a macro:

  #include <PJONSoftwareBitBang.h>
  PJONSoftwareBitBang bus;

In the example above the PJON object is instantiated using the SoftwareBitBang strategy. It is possible to instantiate more than one PJON object using different strategies in the same program:

#include <PJONSoftwareBitBang.h>
#include <PJONEthernetTCP.h>

PJONSoftwareBitBang wiredBus;
PJONEthernetTCP     tcpBus;

The table below lists the strategies available:

Strategy Physical layer Protocol Inclusion
AnalogSampling Light PJDLS #include <PJONAnalogSampling.h>
Any Virtual inheritance Any #include <PJONAny.h>
DualUDP Ethernet/WiFi UDP #include <PJONDualUDP.h>
ESPNOW WiFi ESPNOW #include <PJONESPNOW.h>
EthernetTCP Ethernet/WiFi TCP #include <PJONEthernetTCP.h>
GlobalUDP Ethernet/WiFi UDP #include <PJONGlobalUDP.h>
LocalFile File system None #include <PJONLocalFile.h>
LocalUDP Ethernet/WiFi UDP #include <PJONLocalUDP.h>
MQTTTranslate Ethernet/WiFi MQTT #include <PJONMQTTTranslate.h>
OverSampling Radio PJDLR #include <PJONOverSampling.h>
SoftwareBitBang Wire PJDL #include <PJONSoftwareBitBang.h>
ThroughLoRa Radio LoRa #include <PJONThroughLora.h>
ThroughSerial Wire TSDL #include <PJONThroughSerial.h>

Before using ThroughLoRa be sure to have arduino-LoRa library available. Before using ESPNOW be sure to have installed the required tools as described here. Before using MQTTTranslate be sure to have the ReconnectingMqttClient library available.

Network mode

The network mode can be changed with set_shared_network during runtime, for example moving from local to shared mode:

  bus.set_shared_network(true);

Communication mode

The communication mode can be configured using the set_communication_mode passing PJON_SIMPLEX for simplex or mono-directional mode or PJON_HALF_DUPLEX for half-duplex or bidirectional mode:

  // Run in mono-directional PJON_SIMPLEX mode
  bus.set_communication_mode(PJON_SIMPLEX);
  // Run in bi-directional PJON_HALF_DUPLEX mode
  bus.set_communication_mode(PJON_HALF_DUPLEX);

Router mode

When an instance is configured in router mode it is able to receive all incoming packets without any bus or device id filtering. Use set_router to configure the router mode:

  bus.set_router(true);

Sender information

PJON by default includes the sender's information in the packet, If required include_sender_info can be used as shown below to avoid including sender's information:

  bus.include_sender_info(false);

CRC configuration

With set_crc_32 CRC32 can be forced on each packet sent to higher reliability:

  bus.set_crc_32(true);

Packet handling

If manual packet handling is required, packet automatic deletion can be avoided using set_packet_auto_deletion as shown below:

  bus.set_packet_auto_deletion(false);

Acknowledgement

With the acknowledgement enabled the transmitter has reception certainty. It is by default enabled but can be disabled:

  bus.set_acknowledge(false);

Packet identification

The instance can be configured to include a 16 bits packet identifier to guarantee packet uniqueness. Define PJON_INCLUDE_PACKET_ID as described below, if this constant is not present the feature is not included and around 300 bytes of program memory and 80 bytes of RAM are spared:

  // Include the packet id feature
  #define PJON_INCLUDE_PACKET_ID

  /* Max number of old packet ids stored
     to avoid duplication. If packet duplication
     occurs, set PJON_MAX_RECENT_PACKET_IDS higher */
  #define PJON_MAX_RECENT_PACKET_IDS 10

  #include <PJONSoftwareBitBang.h>

Use set_packet_id to enable the packet identification:

  bus.set_packet_id(true);

See the UsePacketId example to see more in detail how the packet id can be used.

Network service identification

The instance can be configured to include a network service identifier in the packet. Ports from 0 to 8000 are reserved to known network services which index is present in the known network services list, ports from 8001 to 65535 are free for custom use cases. Define PJON_INCLUDE_PORT as described below, if this constant is not present the feature is not used and around 100 bytes of program memory and 2 bytes of RAM are spared:

  // Include the port id feature
  #define PJON_INCLUDE_PORT
  #include <PJONSoftwareBitBang.h>

Use include_port to enable the network service identification:

  bus.include_port(false); // Avoid port inclusion
  bus.include_port(8001);  // Include a port

When a port is configured, packets that contain a different port are discarded. See the PortsUseExample to see more in detail how the port feature can be used.

Hardware identification

The instance can be configured to include the hardware identification. If the feature is used both recipient's and sender's MAC addresses are included in the packet. Define PJON_INCLUDE_MAC as described below, if this constant is not present the feature is not included and around 200 bytes of program memory and 20 bytes of RAM are spared:

  // Include the port id feature
  #define PJON_INCLUDE_MAC
  #include <PJONSoftwareBitBang.h>

  // Device's MAC address
  uint8_t mac[6] = {0, 0, 0, 0, 0, 0};
  PJONSoftwareBitBang bus(mac);

Use include_mac to enable the network service identification:

  bus.include_mac(true); // Include MAC address

See the BlinkTestMAC example to see more in detail how the MAC feature can be used.


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

The PJON protocol handbook

This is the second publication about PJON, which contains the documentation, the specification, many application examples and troubleshooting techniques. The book is Made in Italy and within its 204 pages the whole PJON network protocol stack and its strategies are accurately described with graphs, color pictures and comments on its implementation. Choosing this handy format, you will always have PJON with you, also when not being connected to Internet.


BUY NOW!