/* pupil-fpc - Free pascal requester and subscriber clients for pupil.

Copyright (C) 2016-2017 Carlos Rafael Fernandes Picanço.

The present file is distributed under the terms of the GNU General Public License (GPL v3.0).

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. */

pupil-fpc

Free pascal requester and subscriber clients for pupil.

Dependencies

• libzmq as in 2017-08-30 master.
• SimpleMsgPack serializer/deserializer

For details, please see: https://github.com/cpicanco/pupil-fpc-examples

About ZMQ

The implementation uses pure ZMQ (no czmq) just to keep it simple. For simple req-rep, sub-pub and multipart messaging we don't need czmq.

Examples

Stand alone examples can be found here: https://github.com/cpicanco/pupil-fpc-examples

Pupil Client for TApplication

The class TPupilClient (pupil.client.pas) allow yourLazarus LCL application to send any request to pupil and to react to pupil replies. Also you can subscribe to pupil notifications and messages and define in-app events to them.

TPupilClient was designed to (queue) received replies and messages in a thread-safe, event driven, non blocking way. Queues are executed in the TApplication main thread. TApplication is part of all standard Lazarus LCL applications. Standard lazarus applications are cross-platform for desktops.

To create a requester client do:

uses pupil.client;

{...}

// class instantiation
PupilClient := TPupilClient.Create('127.0.0.1:50020');

// events setup

// subscription messages:
// TNotifyMultipartMessage = procedure(Sender: TObject; AMultiPartMessage : TPupilMessage) of object;
PupilClient.OnCalibrationSuccessful := @YourStartCalibrarionEvent;      
PupilClient.OnCalibrationStopped := @YourStopCalibrarionEvent;
PupilClient.OnRecordingStarted := @YourStartRecordingEvent;
PupilClient.OnMultiPartMessageReceived := @YourMessageReceivedEvent;

// request-reply messages:
// TNotifyRequest = procedure(Sender: TObject; ARequest, AReply: String) of object;
PupilClient.OnReplyReceived := @ReplyReceived;

// fun
PupilClient.Start;

The following requests are available as constants (prefixed with REQ_*):

const
  // start recording with auto generated session name
  // note: may append a string to session name, 'R [session name]'
  REQ_SHOULD_START_RECORDING  = 'R';

  // stop recording
  REQ_SHOULD_STOP_RECORDING = 'r';

  // start currently selected calibration
  REQ_SHOULD_START_CALIBRATION = 'C';

  // stop currently selected calibration
  REQ_SHOULD_STOP_CALIBRATION = 'c';

  // '[T][#32][time]' make pupil timestamps count from [time] on.
  REQ_SYNCHRONIZE_TIME = 'T';

  // get pupil capture timestamp returns a float as string.
  REQ_TIMESTAMP = 't';

  // request recording path
  REQ_RECORDING_PATH = 'P';

You can send requests this way:

PupilClient.Request(REQ_SHOULD_STOP_CALIBRATION);        // non blocking

{or}

PupilClient.Request(REQ_SHOULD_START_CALIBRATION, True); // blocking

To receive pupil messages you must start the subscriber first:

PupilClient.StartSubscriber;        // blocking is recommended

{or}

PupilClient.StartSubscriber(False); // non blocking

After starting the subscriber, you must choose which messages you want to receive. You can do this using filters. You can subscribe to any filter using strings. Many subscription filters are available as constants, they are prefixed with SUB_*. For instance, you can subscribe to all pupil notifications this way:

PupilClient.Subscribe(SUB_ALL_NOTIFICATIONS);

Take a look at the pupil.client.pas for more sub constants.

Pupil Tasks for anything

If TPupilClient and TApplication is too much for what you want, take a look at pupil.tasks.pas and the examples link. They show how to communicate to pupil in a console, application independent style.