owlps/TODO.t2t

Work to do in OwlPS




= Documentation =

- Doxygen: solve problem with structs (member fields are not documented).

- Topics to write on:
  - Architecture
  - Deployment
  - General user manual (common command-line options, etc.)
  - Per module user manual (manpages)




= Global =

- Known bugs:
  - libconfuse bug (Listener & Aggregator): http://bugs.debian.org/639115

- Handle the aggregation format version

  In the aggregation files, a version number describing the file format
  should be added (as the 2nd field, right after the client's MAC
  address). That would allow the positioning server to handle several
  formats instead of just the last version.

- Add a library to parse aggregation files, handling the different
  formats ?

  It could be used by Positioner and external programs.

- Check the size of the received packets to avoid buffer overflows.

- Use select(2) or poll(2)

  Using polling for sockets would avoid setting up some threads,
  especially the autocalibration threads in the Listener, i.e.
  autocalibrate() and autocalibrate_hello(), and listen_for_aps() in the
  Aggregator.

  See also select_tut(2).

- Eliminate remaining exit() calls to avoid memory leaks on exit.

- Use atexit() / on_exit() instead of goto to clean at exit?

- Add option dump-configuration (displays the config & exits).

- Support string-based positioning requests

  Along with the binary requests, implement a string-based request
  format. Each packet will contain a CSV string describing the request's
  information. This will make easier to develop clients in other
  languages than C and over other protocols than UDP.

- Mark arguments as const in function headers if needed

  Mostly done in the Positioner C++ code (which should nonetheless be
  checked), but not constantly in C modules.
  //Done in libowlps & libowlps-client.//

- Allow to use hostnames instead of IP addresses in all modules

  getaddrinfo(3) (or gethostbyname(3)) should be used when opening
  sockets in libowlps, then string buffer size have to be adapted in all
  modules to be able to contain a long hostname.

- Use struct ether_addr to store MAC addresses?

  We could use the struct ether_addr to store binary MAC addresses, and
  convert them to strings with ether_ntoa(3) instead of
  owl_mac_bytes_to_string().

- Handle IPv6.




= Aggregator =

- Rename ap_check_interval to something more meaningful
  (something like autocalibration_order_interval).

- Test for the maximum verbose level.

- Outputs should include all the timestamps

  The CSV output file and the socket should include the capture
  timestamp and the reception timestamp on the Aggregator. This would
  help the Positioner's --replay option (to be adapted to use the
  aggregation time instead of the request time).

- Allow a different aggregation timeout for each request type.

- Refactor got_request().

- got_request(): option for the maximal difference time

  For implicit packets, we consider that packets from the same MAC and
  received within an interval of 10ms are part of the same request. We
  should define an option to allow user to choose the time he wants.




= Listener =

- Known bugs:
  - On OpenWrt Backfire (10.03), when the program is statically linked,
    using both -D and -A at the same time makes the program to block on
    the first thread. This is a known issue of uClibc:
    https://dev.openwrt.org/ticket/4809
  - With autocalibration on, all the CPs declared in listeners.csv must
    be in coverage or the reference points will not be generated.

- Better handling of retried packets ?

  Currently we ignore any packet with the Retry bit. This can lead to
  completely ignore the given packet (or even request) if the original
  packet is never received, which can happen under certain
  circumstances.

  Before changing this behaviour, it must be thought seriously: taking
  into account only the original packet means that all the listeners
  measure the signal strength from the same packet, which is what we
  want in most cases.

  This could be implemented as an option.

- Refactor and review read_packet().

- Handle better the configuration file reading

  Get rid of the "Cannot open configuration file" error, in quiet mode
  and when the default configuration file has to be used (no file
  specified by the user with -f).

- Filter the number of implicit packets per mobile?

  Currently, in passive or mixed mode, //all// the received packets are
  transmitted to the aggregator.

- Option "read-only autocalibration" allowing to listen for
  autocalibration requests without sending requests.

- read_packet(): use ieee80211_header_size for all implicit packets

  Currently the size is corrected only for data packets.

- BSD port

  http://www.unixgarden.com/index.php/programmation/introduction-a-la-programmation-wifi-en-c-sous-netbsd




= Client =

- Log sent requests?

- Allow to use a string for the direction?
  Could be nice, but probably useless.

- Qt version of the client

  We could either modify the current OwlPS Client to add an optional GUI
  (optional dependency on Qt) or create a new, purely graphical client.
  A Qt client would be portable to Android thanks to the Necessitas
  project: http://necessitas.kde.org/

  A port of Qt for Apple iOS was also developed but seems inactive:
  https://qt.gitorious.org/+qt-iphone/qt/qt-iphone-clone




= UDP to HTTP =

- Command-line options (port numbers, -v/-q, -h, -V).

- Delete inactive clients after a given amount of time.

- Refactor prepare_answer().




= Positioner =


== Known bugs ==

- Cannot compute the error (Real) for autocalibration requests.

- Unit tests are currently unmaintained. Do not try to run them.


== Algorithms ==

- Add to the result the information "area error" (whether on not the
  computed result is in the same room as the real position).

- Handle the power and antenna gain difference between the calibration
  mobile (or pseudo-mobile, for autocalibration) and the mobile to
  position.

- MinMax: add option to set the step (and use a different step for X, Y
  and Z?).

- MinMax: reduce the research space as proposed by F. Lassabe (PhD
  report, Fig. 2.6 p. 38 and explanations pp. 38-39).


== Autocalibration ==

- Generate reference points in 3D.

- To select the reference CPs, we should use the distance along with the
  angle and coverage.

- Handle 2 CPs, not only >2 CPs.

- Find why some CalibrationRequest were not deleted when calling
  Stock::delete_calibration_request() (via
  ReferencePoint::delete_requests()).

- Option z-level-number: the Z coordinate represents a floor number. If
  unactivated, Z is in metres and the topology is used to determine a
  change of level.

- Generated CalibrationRequest have always nb_packets == 1.

  It is tricky to set a number of packets for generated requests, since
  the CPs can transmit a different number of packets in their
  autocalibration requests. A solution could be to use the biggest
  number amongst the reference autocalibration requests used. A simpler
  solution could be to assume that all the CPs transmit the same number
  of packets.


== Refactoring ==

- Move Stock::generate_reference_point() & friends to a dedicated class.

- Write a class for Request::type?

  CalibrationRequest::direction uses a dedicated class Direction, why
  not Request::type? That would simplify writing of the type to streams
  (no need to cast each time any more).

- Wi-Fi devices' list
  - Merge Stock::mobiles & Stock::aps?
  - Factorise AccessPointsReaderCSV & MobilesReaderCSV?

- Members renaming
  - InputMedium:
    - current_line_nb & get_current_line_nb()
    - get_next_request() −> read_next_request()
  - Input: get_next_request() −> read_next_request()
  - Area: p_min et p_max −> coord_min et coord_max


== User interface ==

- When reading the CPs, add them to the mobiles' list (or another way to
  be able to have a single entry for a CP).

- Add option positioning.self-calibrate (or autocalibrate), short option
  -A, to activate automatically the options needed by the
  autocalibration.

- Improve --verbose (and/or debug level): print the options, etc.

- Case-insensitive string comparison (for algorithm names, etc.).

- Use a prefix for configuration files (search for config files set with
  relative path in owlps-positioner.cfg in the same directory).


== Optimisation & code improvement ==

- Change ss_t type to int_fast8_t?

- Multithreading:
  - algorithms (parallelize computation of the different algorithms for
    the same request);
  - and/or requests (parallelize computation of several requests).
  -
  See OpenMP.

- ReferencePoint: the request list should be an unordered_set instead of
  a vector, to guarantee the unicity of the elements.

- Pre-allocate vectors' memory with reserve().
 "C++ en action", p. 217.

- Copy of containers to streams (in some operator<<() for instance).
 "C++ en action", p. 275.

- Review all the classes to respect principles exposed in "Coder
  proprement", chapter 6, p. 103: do not implement accessors for each
  class attribute, etc.


== Unit tests ==

- Update (rewrite?) tests.

- Unfinished tests:
  - InputDataReader
  - Input
  - Output
  - Positioning

- Test InterlinkNetworks::compute() ?

- Timestamp: there is a probability of 10^-6 that the value in
  nanoseconds and the rounded value in milliseconds are identical, in
  which case some tests can fail.