data-reception.md

Documentation index

• Addressing
  • set_id device_id get_bus_id set_bus_id get_mac set_mac
• Configuration
  • set_communication_mode set_shared_network set_router include_sender_info set_crc_32 set_packet_auto_deletion set_acknowledge set_packet_id include_port include_mac
• Data reception
  • set_receiver receive
• Data structures
  • PJON_Endpoint PJON_Packet_Info
• Data transmission
  • begin reply reply_blocking send send_packet send_packet_blocking send_repeatedly reply reply_blocking forward forward_blocking
• Error handling
  • set_error
• Routing
  • PJONSimpleSwitch PJONSwitch PJONRouter PJONDynamicRouter PJONInteractiveRouter
• IO setup
  • strategy

---

Data reception

A function of type void is called by the PJON object when a packet is received. This function receives 3 parameters: the received payload of type uint8_t *, its length of type uint16_t and a pointer to a data structure of type const PJON_Packet_Info that contains all packet's metadata:

void receiver_function(uint8_t *payload, uint16_t length, const PJON_Packet_Info &info) {
  // Print received data in the serial monitor
  for(uint16_t i = 0; i < length; i++)
    Serial.print(payload[i]);
};

Register the receiver_function as the receiver callback:

PJONSoftwareBitBang bus;
bus.set_receiver(receiver_function);

Within receiver_function it is possible to process data and meta-data when a packet is received. The PJON_Packet_Info struct contains all the protocol fields present in the packet:

The code below is part of the Arduino compatible PortsUseExample. When the receiver_function is called meta-data present in the info parameter is printed in the serial monitor:

void receiver_function(uint8_t *payload, uint16_t length, const PJON_Packet_Info &info) {
  Serial.print("Header: ");
  Serial.print(info.header, BIN);
  // If packet formatted for a shared medium
  if(info.header & PJON_MODE_BIT) {
    Serial.print(" Receiver bus id: ");
    Serial.print(info.rx.bus_id[0]);
    Serial.print(info.rx.bus_id[1]);
    Serial.print(info.rx.bus_id[2]);
    Serial.print(info.rx.bus_id[3]);
    Serial.print(" Receiver id: ");
    Serial.print(info.rx.id);
    // If sender info is included
    if(info.header & PJON_TX_INFO_BIT) {
      Serial.print(" Sender bus id: ");
      Serial.print(info.tx.bus_id[0]);
      Serial.print(info.tx.bus_id[1]);
      Serial.print(info.tx.bus_id[2]);
      Serial.print(info.tx.bus_id[3]);
    }
  }
  // If sender device id is included
  if(info.header & PJON_TX_INFO_BIT) {
    Serial.print(" Sender id: ");
    Serial.print(info.tx.id);
  }
  // Payload Length
  Serial.print(" Length: ");
  Serial.print(length);
  // If port id is included
  if(info.header & PJON_PORT_BIT) {
    Serial.print(" Port bit: ");
    Serial.print(info.port);
  }
  Serial.println();
};

Use payload before any transmission, the buffer where payload points to is overwritten when a new packet is dispatched.

To understand how to pass custom data to the receiver callback function, see the ClassMemberCallback example. This feature can be used to link other classes or instances passing any sort of data structure.

To receive data the receive function must be called as often as possible:

uint16_t response = bus.receive();

receive returns the following values:

• PJON_ACK (6) if a correct reception occurred
• PJON_NAK (21) if a mistake is found in CRC
• PJON_BUSY (666) if a transmission for other devices is occurring
• PJON_FAIL (65535) if no data is received

If it is required to dedicate a certain time to reception call the receive function passing the maximum reception time in microseconds:

uint16_t response = bus.receive(1000);

Consider that SoftwareBitBang, OverSampling or AnalogSampling are strategies able to receive data only while bus.receive is being executed, otherwise data is lost and transmitter will try again in future. In this particular case it is mandatory to dedicate a certain timeframe, depending on the duration of the other tasks, to efficiently receive data and avoid repetitions.