| ===== |
| Pi433 |
| ===== |
| |
| |
| Introduction |
| ============ |
| This driver is for controlling pi433, a radio module for the Raspberry Pi |
| (www.pi433.de). It supports transmission and reception. It can be opened |
| by multiple applications for transmission and reception. While transmit |
| jobs are queued and processed automatically in the background, the first |
| application asking for reception will block out all other applications |
| until something gets received terminates the read request. |
| The driver supports on the fly reloading of the hardware fifo of the rf |
| chip, thus enabling for much longer telegrams than the hardware fifo size. |
| |
| Description of driver operation |
| =============================== |
| |
| a) transmission |
| |
| Each transmission can take place with a different configuration of the rf |
| module. Therefore each application can set its own set of parameters. The driver |
| takes care, that each transmission takes place with the parameterset of the |
| application, that requests the transmission. To allow the transmission to take |
| place in the background, a tx thread is introduced. |
| The transfer of data from the main thread to the tx thread is realised by a |
| kfifo. With each write request of an application, the passed in data and the |
| corresponding parameter set gets written to the kfifo. |
| On the other "side" of the kfifo, the tx thread continuously checks, whether the |
| kfifo is empty. If not, it gets one set of config and data from the kfifo. If |
| there is no receive request or the receiver is still waiting for something in |
| the air, the rf module is set to standby, the parameters for transmission gets |
| set, the hardware fifo of the rf chip gets preloaded and the transmission gets |
| started. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling |
| much longer telegrams than the hardware fifo size. If the telegram is sent and there |
| is more data available in the kfifo, the procedure is repeated. If not the |
| transmission cycle ends. |
| |
| b) reception |
| |
| Since there is only one application allowed to receive data at a time, for |
| reception there is only one configuration set. |
| As soon as an application sets a request for receiving a telegram, the reception |
| configuration set is written to the rf module and it gets set into receiving mode. |
| Now the driver is waiting, that a predefined RSSI level (signal strength at the |
| receiver) is reached. Until this hasn't happened, the reception can be |
| interrupted by the transmission thread at any time to insert a transmission cycle. |
| As soon as the predefined RSSI level is met, a receiving cycle starts. Similar |
| as described for the transmission cycle the read out of the hardware fifo is done |
| dynamically. Upon each hardware fifo threshold interrupt, a portion of data gets |
| read. So also for reception it is possible to receive more data than the hardware |
| fifo can hold. |
| |
| |
| Driver API |
| ========== |
| |
| The driver is currently implemented as a character device. Therefore it supports |
| the calls open, ioctl, read, write and close. |
| |
| |
| params for ioctl |
| ---------------- |
| |
| There are four options: |
| PI433_IOC_RD_TX_CFG - get the transmission parameters from the driver |
| PI433_IOC_WR_TX_CFG - set the transmission parameters |
| PI433_IOC_RD_RX_CFG - get the receiving parameters from the driver |
| PI433_IOC_WR_RX_CFG - set the receiving parameters |
| |
| The tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission. |
| It is divided into two sections: rf parameters and packet format. |
| |
| rf params: |
| frequency |
| frequency used for transmission. |
| Allowed values: 433050000...434790000 |
| bit_rate |
| bit rate used for transmission. |
| Allowed values: ##### |
| dev_frequency |
| frequency deviation in case of FSK. |
| Allowed values: 600...500000 |
| modulation |
| FSK - frequency shift key |
| OOK - On-Off-key |
| modShaping |
| shapingOff - no shaping |
| shaping1_0 - gauss filter with BT 1 (FSK only) |
| shaping0_5 - gauss filter with BT 0.5 (FSK only) |
| shaping0_3 - gauss filter with BT 0.3 (FSK only) |
| shapingBR - filter cut off at BR (OOK only) |
| shaping2BR - filter cut off at 2*BR (OOK only) |
| pa_ramp (FSK only) |
| ramp3400 - amp ramps up in 3.4ms |
| ramp2000 - amp ramps up in 2.0ms |
| ramp1000 - amp ramps up in 1ms |
| ramp500 - amp ramps up in 500us |
| ramp250 - amp ramps up in 250us |
| ramp125 - amp ramps up in 125us |
| ramp100 - amp ramps up in 100us |
| ramp62 - amp ramps up in 62us |
| ramp50 - amp ramps up in 50us |
| ramp40 - amp ramps up in 40us |
| ramp31 - amp ramps up in 31us |
| ramp25 - amp ramps up in 25us |
| ramp20 - amp ramps up in 20us |
| ramp15 - amp ramps up in 15us |
| ramp12 - amp ramps up in 12us |
| ramp10 - amp ramps up in 10us |
| tx_start_condition |
| fifo_level - transmission starts, if fifo is filled to |
| threshold level |
| fifo_not_empty - transmission starts, as soon as there is one |
| byte in internal fifo |
| repetitions |
| This gives the option, to send a telegram multiple times. Default: 1 |
| |
| packet format: |
| enable_preamble |
| optionOn - a preamble will be automatically generated |
| optionOff - no preamble will be generated |
| enable_sync |
| optionOn - a sync word will be automatically added to |
| the telegram after the preamble |
| optionOff - no sync word will be added |
| Attention: While possible to generate sync without preamble, the |
| receiver won't be able to detect the sync without preamble. |
| enable_length_byte |
| optionOn - the length of the telegram will be automatically |
| added to the telegram. It's part of the payload |
| optionOff - no length information will be automatically added |
| to the telegram. |
| Attention: For telegram length over 255 bytes, this option can't be used |
| Attention: should be used in combination with sync, only |
| enable_address_byte |
| optionOn - the address byte will be automatically added to the |
| telegram. It's part of the payload |
| optionOff - the address byte will not be added to the telegram. |
| The address byte can be used for address filtering, so the receiver |
| will only receive telegrams with a given address byte. |
| Attention: should be used in combination with sync, only |
| enable_crc |
| optionOn - an crc will be automatically calculated over the |
| payload of the telegram and added to the telegram |
| after payload. |
| optionOff - no crc will be calculated |
| preamble_length |
| length of the preamble. Allowed values: 0...65536 |
| sync_length |
| length of the sync word. Allowed values: 0...8 |
| fixed_message_length |
| length of the payload of the telegram. Will override the length |
| given by the buffer, passed in with the write command. Will be |
| ignored if set to zero. |
| sync_pattern[8] |
| contains up to eight values, that are used as the sync pattern |
| on sync option |
| address_byte |
| one byte, used as address byte on address byte option. |
| |
| |
| The rx configuration is transferred via struct pi433_rx_cfg, the parameterset for receiving. It is divided into two sections: rf parameters and packet format. |
| |
| rf params: |
| frequency |
| frequency used for transmission. |
| Allowed values: 433050000...434790000 |
| bit_rate |
| bit rate used for transmission. |
| Allowed values: ##### |
| dev_frequency |
| frequency deviation in case of FSK. |
| Allowed values: 600...500000 |
| modulation |
| FSK - frequency shift key |
| OOK - on off key |
| rssi_threshold |
| threshold value for the signal strength on the receiver input. |
| If this value is exceeded, a reception cycle starts |
| Allowed values: 0...255 |
| threshold_decrement |
| in order to adapt to different levels of singnal strength, over |
| time the receiver gets more and more sensitive. This value |
| determs, how fast the sensitivity increases. |
| step_0_5db - increase in 0,5dB steps |
| step_1_0db - increase in 1 db steps |
| step_1_5db - increase in 1,5dB steps |
| step_2_0db - increase in 2 db steps |
| step_3_0db - increase in 3 db steps |
| step_4_0db - increase in 4 db steps |
| step_5_0db - increase in 5 db steps |
| step_6_0db - increase in 6 db steps |
| antenna_impedance |
| sets the electrical adoption of the antenna |
| fifty_ohm - for antennas with an impedance of 50Ohm |
| two_hundred_ohm - for antennas with an impedance of 200Ohm |
| lna_gain |
| sets the gain of the low noise amp |
| automatic - lna gain is determined by an agc |
| max - lna gain is set to maximum |
| max_minus_6 - lna gain is set to 6db below max |
| max_minus_12 - lna gain is set to 12db below max |
| max_minus_24 - lna gain is set to 24db below max |
| max_minus_36 - lna gain is set to 36db below max |
| max_minus_48 - lna gain is set to 48db below max |
| bw_mantisse |
| sets the bandwidth of the channel filter - part one: mantisse. |
| mantisse16 - mantisse is set to 16 |
| mantisse20 - mantisse is set to 20 |
| mantisse24 - mantisse is set to 24 |
| bw_exponent |
| sets the bandwidth of the channel filter - part two: exponent. |
| Allowd values: 0...7 |
| dagc; |
| operation mode of the digital automatic gain control |
| normal_mode |
| improve |
| improve_for_low_modulation_index |
| |
| packet format: |
| enable_sync |
| optionOn - sync detection is enabled. If configured sync pattern |
| isn't found, telegram will be internally discarded |
| optionOff - sync detection is disabled. |
| enable_length_byte |
| optionOn - First byte of payload will be used as a length byte, |
| regardless of the amount of bytes that were requested |
| by the read request. |
| optionOff - Number of bytes to be read will be set according to |
| amount of bytes that were requested by the read request. |
| Attention: should be used in combination with sync, only |
| enable_address_filtering; |
| filtering_off - no address filtering will take place |
| node_address - all telegrams, not matching the node |
| address will be internally discarded |
| node_or_broadcast_address - all telegrams, neither matching the |
| node, nor the broadcast address will |
| be internally discarded |
| Attention: Sync option must be enabled in order to use this feature |
| enable_crc |
| optionOn - a crc will be calculated over the payload of |
| the telegram, that was received. If the |
| calculated crc doesn't match to two bytes, |
| that follow the payload, the telegram will be |
| internally discarded. |
| Attention: This option is only operational if sync on and fixed length |
| or length byte is used |
| sync_length |
| Gives the length of the payload. |
| Attention: This setting must meet the setting of the transmitter, |
| if sync option is used. |
| fixed_message_length |
| Overrides the telegram length either given by the first byte of |
| payload or by the read request. |
| bytes_to_drop |
| gives the number of bytes, that will be dropped before transferring |
| data to the read buffer |
| This option is only useful if all packet helper are switched |
| off and the rf chip is used in raw receiving mode. This may be |
| needed, if a telegram of a third party device should be received, |
| using a protocol not compatible with the packet engine of the rf69 chip. |
| sync_pattern[8] |
| contains up to eight values, that are used as the sync pattern |
| on sync option. |
| This setting must meet the configuration of the transmitting device, |
| if sync option is enabled. |
| node_address |
| one byte, used as node address byte on address byte option. |
| broadcast_address |
| one byte, used as broadcast address byte on address byte option. |
| |
| |
