Oww servers can transmit data to clients using the "oww_trx" (or now "Owwl") protocol. Owwl was written at first to facilitate the creation of client programs for this protocol, but has since been expanded to provide server-side functions as well. In addition, other, non-weather, device types are being added, so that owwl can be used to transfer data at high speed from the focal plane computer (FPC) of the QUEST CMB polarization telescope.
./configure make su -c "make install"
This will build and install the library and header files, in the usual location for your system. Check out the configure options (./configure --help) if you want to change this.
If your system doesn't have the autotools, that's a shame (they're really handy), but you can still build and install owwl manually. You will need a C compiler, and a typical C library, that supports BSD sockets. Owwl does not link to any other libraries.
owwl_new_conn(int socket, void *user_data) ;
Here socket is the file descriptor of an existing connexion to an owwl server, and user_data is some arbitrary pointer to be associated with the conn. For a server-only application use socket = 0, and never call owwl_read().
Most owwl calls will make use of the returned owwl_conn pointer.
owwl_read() returns:
Once a full message has been collected, decoded message data will be available in the owwl_conn::data data array.
To call a function for each data stream use owwl_foreach().
To receive connexions from clients you must first provide a listing socket to owwl_tx_new_server(). This will make a note of the socket, and initialize a list structure for connected clients. You can do this for many sockets, e.g. you could have both a TCP socket and a LOCAL (UNIX) socket.
To receive client connexions you must repeatedly call owwl_tx_poll_servers(). This will issue calls to poll, to check for new connexion requests.
Each time you want to send a data message to your clients you must first build it in a buffer, using owwl_tx_build(). This will assemble the data from all data streams in the conn into the buffer. Then send the message with owwl_tx().
The smallest element of owwl data is the 4-byte (i.e. 32-bit) word. Words are sent in network byte order.
Words are grouped together in chunks, consisting of a word giving the number of words following and the chunk type, and then the words.
At the highest level, owwl messages consist of two parts:
The message is built by calling owwl_tx_build(), which constructs first the header and then the body.
| Header Word No. | Value |
| 0 | OWW_TRX_HEAD + No. words following |
| 1 | 1-word NULL-terminated text string "<tt>Oww</tt>" |
| 2 | Message size |
| 3 | Message type |
| 4 | Protocol version number |
The message size is the total length of the message (header + body) in bytes.
Message types may be:
| OWW_TRX_MSG_WSDATA | 1 | Normal data stream update |
| OWW_TRX_MSG_UPDT | 2 | Update interval has changed |
| OWW_TRX_MSG_MORT | 3 | Server about to die |
| OWW_TRX_MSG_ANNOUN | 4 | Initial announcement |
| Message type | Message body |
| OWW_TRX_MSG_WSDATA | Data streams |
| OWW_TRX_MSG_UPDT | latitude and longitude owwl_conn::latitude owwl_conn::longitude |
| OWW_TRX_MSG_MORT | No body |
| OWW_TRX_MSG_ANNOUN | Update interval owwl_conn::interval |
The simple bodies consist of a single chunk, consisting of the chunk indentifier code (e.g. OWW_TRX_MSG_UPDT) followed by words giving the values.
Floating point values are passed as 4-byte IEEE reals, and integer values as 4-byte integers, all in network byte order.
This consists of a time chunk, giving the timestamp for the data values, followed by a chunk for each data stream.
Four integer values are given in the time chunk:
| Word No. | Value |
| 0 | OWW_TRX_TIME + 4 |
| 1 | Data timestamp Given as Unix time owwl_conn::data_time |
| 2 | Time in local timezone |
| 3 | Update interval owwl_conn::interval |
| 4 | Microsecond part to timestamp owwl_conn::data_time_usec |
The details of the chunks for different data stream types can best be seen from the source to the owwl_tx_add_data function.
The chunk identifier for each data stream is constructed from four values (from the low byte to the high byte):
To construct the identifier word, the chunk length is added to the serial number multiplied by 256, the device sub-type, and the device type.
See Header Word Codes for a list of the values for building chunk identifiers.
There follow the definitions of the header and data words for each data stream type.
| Thermometer | ||
|---|---|---|
| OWW_TRX_T | + [OWW_TRX_SUB_TRH | OWW_TRX_SUB_TB] | + i * OWW_TRX_SERIAL + 1 |
| T owwl_data_temperature::T | float | Temperature in C |
| Barometer | ||
| OWW_TRX_BP | + 0 | + i * OWW_TRX_SERIAL + 1 |
| bp owwl_data_barometer::bp | float | Barometric pressure in mbar |
| Humidity | ||
| OWW_TRX_RH | + 0 | + i * OWW_TRX_SERIAL + 1 |
| RH owwl_data_humidity::RH | float | Relative humidity in % |
| Wind | ||
| OWW_TRX_WIND | + 0 | + i * OWW_TRX_SERIAL + 3 |
| bearing owwl_data_wind::bearing * 100.0 | long | Wind bearing (clockwise from North) in units of 0.01 degrees |
| speed owwl_data_wind::speed | float | Wind speed (m.s<sup>-1) |
| gust owwl_data_wind::gust | float | Wind gust speed (m.s<sup>-1) |
| Rain | ||
| OWW_TRX_RAIN | + 0 | + i * OWW_TRX_SERIAL + 4 |
| Count owwl_data_rain::rain_count | long | Monotonic count (tips) |
| Rain owwl_data_rain::rain_since_reset | float | Rain since reset (mm) |
| Reset time owwl_data_rain::rain_reset_time | long | Unix time of reset |
| Rain rate owwl_data_rain::rain_rate | float | Rainfall rate (mm.hour<sup>-1) |
| General purpose counter | ||
| OWW_TRX_GPC | + 0 | + i * OWW_TRX_SERIAL + 5 |
| Calibrated owwl_data_gpc::gpc_calibrated | float | Calibrated count |
| Delta owwl_data_gpc::gpc_delta | float | Calibrated delta |
| Count owwl_data_gpc::gpc_count | long | Monotonic count |
| Rate owwl_data_gpc::gpc_rate | float | Count rate |
| Reset time owwl_data_gpc::gpc_reset_time | long | Unix time of reset |
| PSB | ||
| OWW_TRX_PSB | + 0 | + i * OWW_TRX_SERIAL + 2 |
| A owwl_data_psb::psb_a | int | PSB channel A |
| B owwl_data_psb::psb_b | int | PSB channel B |
| Diode | ||
| OWW_TRX_DIODE | + 0 | + i * OWW_TRX_SERIAL + 1 |
| A owwl_data_diode::V | float | Diode voltage |
| GRT | ||
| OWW_TRX_GRT | + 0 | + i * OWW_TRX_SERIAL + 3 |
| A owwl_data_grt:V | float | GRT in-phase voltage |
| A owwl_data_grt:Vq | float | GRT quadrature-phase voltage |
| A owwl_data_grt:I | float | GRT current |
| Cryo | ||
| OWW_TRX_CRYO | + [OWW_TRX_SUB_TCD | OWW_TRX_SUB_TCG] | + i * OWW_TRX_SERIAL + 1 |
| T owwl_data_cryo::T | float | Temperature in K |
| Heater | ||
| OWW_TRX_HEATER | + 0 | + i * OWW_TRX_SERIAL + 1 |
| V owwl_data_heater::V | float | Heater Voltage in V |
| Resistance | ||
| OWW_TRX_RESISTANCE | + 0 | + i * OWW_TRX_SERIAL + 1 |
| R owwl_data_resistance::R | float | Resistance in Ohms
|
1.4.6