drivers/staging/pi433/Documentation/pi433.txt

   1 =====
   2 Pi433
   3 =====
   4
   5
   6 Introduction
   7 ============
   8 This driver is for controlling pi433, a radio module for the Raspberry Pi
   9 (www.pi433.de). It supports transmission and reception. It can be opened
  10 by multiple applications for transmission and reception. While transmit
  11 jobs were queued and process automatically in the background, the first
  12 application asking for reception will block out all other applications
  13 until something gets received terminates the read request.
  14 The driver supports on the fly reloading of the hardware fifo of the rf
  15 chip, thus enabling for much longer telegrams then hardware fifo size.
  16
  17 Discription of driver operation
  18 ===============================
  19
  20 a) transmission
  21
  22 Each transmission can take place with a different configuration of the rf
  23 module. Therefore each application can set its own set of parameters. The driver
  24 takes care, that each transmission takes place with the parameterset of the
  25 application, that requests the transmission. To allow the transmission to take
  26 place in the background, a tx thread is introduced.
  27 The transfer of data from the main thread to the tx thread is realised by a
  28 kfifo. With each write request of an application, the passed in data and the
  29 corresponding parameter set gets written to the kfifo.
  30 On the other "side" of the kfifo, the tx thread continuously checks, whether the
  31 kfifo is empty. If not, it gets one set of config and data from the kfifo. If
  32 there is no receive request or the receiver is still waiting for something in
  33 the air, the rf module is set to standby, the parameters for transmission gets
  34 set, the hardware fifo of the rf chip gets preloaded and the transmission gets
  35 started. Upon hardware fifo threshold interrupt it gets reloaded, thus enabling
  36 much longer telegrams than the hardware fifo size. If the telegram is sent and there
  37 is more data available in the kfifo, the procedure is repeated. If not the
  38 transmission cycle ends.
  39
  40 b) reception
  41
  42 Since there is only one application allowed to receive data at a time, for
  43 reception there is only one configuration set.
  44 As soon as an application sets a request for receiving a telegram, the reception
  45 configuration set is written to the rf module and it gets set into receiving mode.
  46 Now the driver is waiting, that a predefined RSSI level (signal strength at the
  47 receiver) is reached. Until this hasn't happened, the reception can be
  48 interrupted by the transmission thread at any time to insert a transmission cycle.
  49 As soon as the predefined RSSI level is meat, a receiving cycle starts. Similar
  50 as described for the transmission cycle the read out of the hardware fifo is done
  51 dynamically. Upon each hardware fifo threshold interrupt, a portion of data gets
  52 read. So also for reception it is possible to receive more data then the hardware
  53 fifo can hold.
  54
  55
  56 Driver API
  57 ==========
  58
  59 The driver is currently implemented as a character device. Therefore it supports
  60 the calls open, ioctl, read, write and close.
  61
  62
  63 params for ioctl
  64 ----------------
  65
  66 There are four options:
  67 PI433_IOC_RD_TX_CFG - get the transmission parameters from the driver
  68 PI433_IOC_WR_TX_CFG - set the transmission parameters
  69 PI433_IOC_RD_RX_CFG - get the receiving parameters from the driver
  70 PI433_IOC_WR_RX_CFG - set the receiving parameters
  71
  72 The tx configuration is transferred via struct pi433_tx_cfg, the parameterset for transmission.
  73 It is divided into two sections: rf parameters and packet format.
  74
  75 rf params:
  76         frequency
  77                 frequency used for transmission.
  78                 Allowed values: 433050000...434790000
  79         bit_rate
  80                 bit rate used for transmission.
  81                 Allowed values: #####
  82         dev_frequency
  83                 frequency deviation in case of FSK.
  84                 Allowed values: 600...500000
  85         modulation
  86                 FSK - frequency shift key
  87                 OOK - On-Off-key
  88         modShaping
  89                 shapingOff      - no shaping
  90                 shaping1_0      - gauss filter with BT 1 (FSK only)
  91                 shaping0_5      - gauss filter with BT 0.5 (FSK only)
  92                 shaping0_3      - gauss filter with BT 0.3 (FSK only)
  93                 shapingBR       - filter cut off at BR (OOK only)
  94                 shaping2BR      - filter cut off at 2*BR (OOK only)
  95         pa_ramp (FSK only)
  96                 ramp3400        - amp ramps up in 3.4ms
  97                 ramp2000        - amp ramps up in 2.0ms
  98                 ramp1000        - amp ramps up in 1ms
  99                 ramp500         - amp ramps up in 500us
 100                 ramp250         - amp ramps up in 250us
 101                 ramp125         - amp ramps up in 125us
 102                 ramp100         - amp ramps up in 100us
 103                 ramp62          - amp ramps up in 62us
 104                 ramp50          - amp ramps up in 50us
 105                 ramp40          - amp ramps up in 40us
 106                 ramp31          - amp ramps up in 31us
 107                 ramp25          - amp ramps up in 25us
 108                 ramp20          - amp ramps up in 20us
 109                 ramp15          - amp ramps up in 15us
 110                 ramp12          - amp ramps up in 12us
 111                 ramp10          - amp ramps up in 10us
 112         tx_start_condition
 113                 fifo_level      - transmission starts, if fifo is filled to
 114                                   threshold level
 115                 fifo_not_empty  - transmission starts, as soon as there is one
 116                                   byte in internal fifo
 117         repetitions
 118                 This gives the option, to send a telegram multiple times. Default: 1
 119
 120 packet format:
 121         enable_preamble
 122                 optionOn        - a preamble will be automatically generated
 123                 optionOff       - no preamble will be generated
 124         enable_sync
 125                 optionOn        - a sync word will be automatically added to
 126                                   the telegram after the preamble
 127                 optionOff       - no sync word will be added
 128                 Attention: While possible to generate sync without preamble, the
 129                 receiver won't be able to detect the sync without preamble.
 130         enable_length_byte
 131                 optionOn        - the length of the telegram will be automatically
 132                                   added to the telegram. It's part of the payload
 133                 optionOff       - no length information will be automatically added
 134                                   to the telegram.
 135                 Attention: For telegram length over 255 bytes, this option can't be used
 136                 Attention: should be used in combination with sync, only
 137         enable_address_byte
 138                 optionOn        - the address byte will be automatically added to the
 139                                   telegram. It's part of the payload
 140                 optionOff       - the address byte will not be added to the telegram.
 141                 The address byte can be used for address filtering, so the receiver
 142                 will only receive telegrams with a given address byte.
 143                 Attention: should be used in combination with sync, only
 144         enable_crc
 145                 optionOn        - an crc will be automatically calculated over the
 146                                   payload of the telegram and added to the telegram
 147                                   after payload.
 148                 optionOff       - no crc will be calculated
 149         preamble_length
 150                 length of the preamble. Allowed values: 0...65536
 151         sync_length
 152                 length of the sync word. Allowed values: 0...8
 153         fixed_message_length
 154                 length of the payload of the telegram. Will override the length
 155                 given by the buffer, passed in with the write command. Will be
 156                 ignored if set to zero.
 157         sync_pattern[8]
 158                 contains up to eight values, that are used as the sync pattern
 159                 on sync option
 160         address_byte
 161                 one byte, used as address byte on address byte option.
 162
 163
 164 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.
 165
 166 rf params:
 167         frequency
 168                 frequency used for transmission.
 169                 Allowed values: 433050000...434790000
 170         bit_rate
 171                 bit rate used for transmission.
 172                 Allowed values: #####
 173         dev_frequency
 174                 frequency deviation in case of FSK.
 175                 Allowed values: 600...500000
 176         modulation
 177                 FSK - frequency shift key
 178                 OOK - on off key
 179         rssi_threshold
 180                 threshold value for the signal strength on the receiver input.
 181                 If this value is exceeded, a reception cycle starts
 182                 Allowed values: 0...255
 183         threshold_decrement
 184                 in order to adapt to different levels of singnal strength, over
 185                 time the receiver gets more and more sensitive. This value
 186                 determs, how fast the sensitivity increases.
 187                 step_0_5db      - increase in 0,5dB steps
 188                 step_1_0db      - increase in 1 db steps
 189                 step_1_5db      - increase in 1,5dB steps
 190                 step_2_0db      - increase in 2 db steps
 191                 step_3_0db      - increase in 3 db steps
 192                 step_4_0db      - increase in 4 db steps
 193                 step_5_0db      - increase in 5 db steps
 194                 step_6_0db      - increase in 6 db steps
 195         antenna_impedance
 196                 sets the electrical adoption of the antenna
 197                 fifty_ohm       - for antennas with an impedance of 50Ohm
 198                 two_hundred_ohm - for antennas with an impedance of 200Ohm
 199         lna_gain
 200                 sets the gain of the low noise amp
 201                 automatic       - lna gain is determined by an agc
 202                 max             - lna gain is set to maximum
 203                 max_minus_6     - lna gain is set to  6db below max
 204                 max_minus_12    - lna gain is set to 12db below max
 205                 max_minus_24    - lna gain is set to 24db below max
 206                 max_minus_36    - lna gain is set to 36db below max
 207                 max_minus_48    - lna gain is set to 48db below max
 208         bw_mantisse
 209                 sets the bandwidth of the channel filter - part one: mantisse.
 210                 mantisse16      - mantisse is set to 16
 211                 mantisse20      - mantisse is set to 20
 212                 mantisse24      - mantisse is set to 24
 213         bw_exponent
 214                 sets the bandwidth of the channel filter - part two: exponent.
 215                 Allowd values: 0...7
 216         dagc;
 217                 operation mode of the digital automatic gain control
 218                 normal_mode
 219                 improve
 220                 improve_for_low_modulation_index
 221
 222  packet format:
 223         enable_sync
 224                 optionOn  - sync detection is enabled. If configured sync pattern
 225                             isn't found, telegram will be internally discarded
 226                 optionOff - sync detection is disabled.
 227         enable_length_byte
 228                 optionOn   - First byte of payload will be used as length byte,
 229                              regardless of the amount of bytes that were requested
 230                              by the read request.
 231                 optionOff  - Number of bytes to be read will be set according to
 232                              amount of bytes that were requested by the read request.
 233                 Attention: should be used in combination with sync, only
 234         enable_address_filtering;
 235                 filtering_off             - no address filtering will take place
 236                 node_address              - all telegrams, not matching the node
 237                                             address will be internally discarded
 238                 node_or_broadcast_address - all telegrams, neither matching the
 239                                             node, nor the broadcast address will
 240                                             be internally discarded
 241                 Attention: Sync option must be enabled in order to use this feature
 242         enable_crc
 243                 optionOn        - a crc will be calculated over the payload of
 244                                   the telegram, that was received. If the
 245                                   calculated crc doesn't match to two bytes,
 246                                   that follow the payload, the telegram will be
 247                                   internally discarded.
 248                 Attention: This option is only operational if sync on and fixed length
 249                 or length byte is used
 250         sync_length
 251                 Gives the length of the payload.
 252                 Attention: This setting must meet the setting of the transmitter,
 253                 if sync option is used.
 254         fixed_message_length
 255                 Overrides the telegram length either given by the first byte of
 256                 payload or by the read request.
 257         bytes_to_drop
 258                 gives the number of bytes, that will be dropped before transferring
 259                 data to the read buffer
 260                 This option is only useful if all packet helper are switched
 261                 off and the rf chip is used in raw receiving mode. This may be
 262                 needed, if a telegram of a third party device should be received,
 263                 using a protocol not compatible with the packet engine of the rf69 chip.
 264         sync_pattern[8]
 265                 contains up to eight values, that are used as the sync pattern
 266                 on sync option.
 267                 This setting must meet the configuration of the transmitting device,
 268                 if sync option is enabled.
 269         node_address
 270                 one byte, used as node address byte on address byte option.
 271         broadcast_address
 272                 one byte, used as broadcast address byte on address byte option.
 273
 274