Abstract

This is a short guide to the current experimental Version of the Velobox' Websocket-API for the saddle pressure analysis.

Introduction

The new Velobox WS/HTTP-server supports "applications" that work largely independent from each other on top of a "kernel". We could also talk about "application servers" but "application" is shorter. You start an application with

Although more than one client can connect to the same application, they won't work independently from each other.

The "Satteldruckanalyse"-Application

Commands applying to analysis and Bluetooth

The number 0 stands for the live image, 1 for the left and 2 for the right integrated image. Number 3 stands for a retrieved image. [something] denotes an optional input for "something", a|b an alternative. m...[n] is a range.

• record {[-force] <duration> [1|2]} | cancel
  
  • Start recording 1 or 2 rsp. for <duration> seconds.
    After recording the results will be sent. If no recording is specified 1 is the default. Use the -force option to override unstored recordings. Without -force an unstored recording will cause an error.
  • Cancel running recording
    No results will be sent. This is the preferred method to avoid an "unstored" error.
• set mask {nomask|standard|large|custom|<name>}|{[-store [<name>]] <pattern>}
  Select one of the predefined masks or specify a new mask.
  <pattern> is a sequence of ones and zeros that defines the custom mask.
  The new mask will be stored with the name specified by the -store option where "custom" is the default. Without the -store option "custom" is the default too. The predefined masks 'nomask', 'standard' and 'large' cannot be overridden. A mask name must consist of alphanumerical characters only and must not begin with a digit.
• set jpeg colorcontrast 0...7
  Set color contrast for all three images.
• set jpeg bgcolor #rrggbb
  Set background color for all three images.
  rr, gg, bb stands for a hex value for red, green an blue respectively.
• set jpeg 0|1|2|3 grid no|dotted|solid
  Shows or doesn't show the grid that separates the measuring points
• set jpeg 0|1|2|3 resolution 1...
  Sets the number of pixels generated per measuring point
  Although there is no upper limit, a large number will probabely knock out the Velobox.
• set jpeg 0|1|2|3 frame 0...
  Draws a black frame around the generated image of the width (pixels) specified.
• set jpeg 0|1|2|3 quality 0...100
  Sets quality for JPEG compression.
• set jpeg 0|1|2|3 mask show|hide
  Shows or hides the mask.
• set compare on|off
  Switch compare mode on or off
  
• get mask <name>
  Fetch mask specified by <name>
  This will cause the wsevent 'mask' with the keys 'name' and 'values'.
  The mask can be used a starting point for a mask editor.
• get appquestions [<lang>]¹⁾
  Fetch questions whose answers will be recorded for a client during a fitting session. They correspond to the questions ask by the Velometrik^® product selection webservice.
• get appsettings
  Fetch all settings done by a set command (or config) as a single JSON Object. (Details are explained below.)
• config n_update_live|n_update_int 1...
  Configure application behavior
  Update every n_update_live-th live image
  Update every n_update_int-th integrated image
  (Affects only JPEG-Generation)
• status <what>
  Returns status information. <what> may be:
  

  channel{1|2}:	recording status of that channel
  	finished true|false
  	recording_id (0 if not stored)
  imagespeed:	number of pressure images received during 1s1)
  temp:	CPU temperature in degrees centigrade

  ¹⁾Images without any pressure will not be counted.
  
• version²⁾
  Query Version
  The versions of vmkstationd (key vmkstationd) and of the application (key app) will be returned.
• Bluetooth commands
  • btconnect [<device_name>]
    Connect to the only device available or to the device specified
    If the device is not paired yet, it will be paired before.
  • btdisconnect
    End current connection
    The device keeps paired.
  • btremove [<device_name>]
    Remove the device given by <device_name> from the paired devices.
    If <device_name> is not given, all devices whose name starts with "SmartCover" will be removed.
    The usage of this command is recommended in any case of connection failure with the following steps:
    1. Inform user about the connection failure (The reason usually is unimportant.)
    2. Ask user if he wants to retry
    3. Send btremove (If the user wants to retry)
    4. Send btconect again
  • btversion
    Query version of internal Bluetooth agent
    (A version change could affect the btevents.)

¹⁾ Questions are subdivided in an array of sections. Each section object has a code, a text for display and an array of questions (named fragen). Each question has a code (equal to the code in Velometrik^®s product selection webservice), a response type (antworttyp), a text for display and, depending on the response type, an array of defaults. The respond types are:

• 1: numeric value
• 2: yes/no answer
• 3: numeric value from defaults
• 4: string value from defaults

Pelvis rotation

                           v-Secondary axis
        | c1               | front                  | c2
       -+------------------+------------------------+- Front tangent
        |                  |                        |
        |                  |                        |
        |                  |                        |
        | left             | center                 | right
       -+------------------+------------------------+- <-Principal axis
        |                  |                        |
        |                  |                        |
        | c4               | rear                   | c3
       -+------------------+------------------------+- Rear tangent
        |                  |                        |
        Left tangent                                Right tangent
        

Veloscore

The "veloscore" is a measure of pressure distribution. Values are from 0 to 100 where 0 means "All pressure is on a single point." and 100 means "All points have the same pressure.".

JSON responses

Every JSON response has the key "wsevent" which classifies the JSON message. Depending on the message class there may be more keys specific for that message class. Until now there are the following definitions:

Commands applying to database

The Velobox has a database for storing the results of the saddle fittings. It can be accessed by SQL. Extra commands ease the handling of images by creating JPEG images with the current JPEG setting from the stored pressure values and the mask. Together they support a reasonable workflow.

• sql <SQL command>
  Execute the given SQL command.
  This command returns the wsevent "sqlresult" with the key "rows" whose value is an array of the rows returned by the SQL command. Each row is an object with the column names as keys. In case of a NULL value the corresponding key is missing.
• session <subcommand> ...
  Commands to handle sessions
  Fittings are organized in sessions. Every session has a number of recordings. A session must be started before a recording can be stored.
  The subcommands
  
  • start <client_id>|<client_info>
    
    • Start a new session for the client with <client_id>
      
    • Start a new session for a new client specified by <client_info>.
      <client_info> is a JSON object string with the keys 'forename', 'surname' and 'email'. Non of these keys is mandatory. Usually it is not a good idea to store a client without any of these data because the only way to find him again will be the autmatically generated timestamp.
      The client_id of the new client can be retrieved by
      SELECT next_id-1 AS client_id FROM nextids WHERE table_name = 'clients'
    Both versions create a new row in the sessions table. The session_id can be retrieved by
    SELECT next_id-1 AS session_id FROM nextids WHERE table_name = 'sessions'
  • finish
    Finish the current session
    Finishing a session means checking for unsaved recordings and deleting empty sessions. (sessions without any recordings)
    Attention! The application server cannot know about unsaved data on the client (product, product_label or notes).
  • restart <session_id>
    Restart an earlier session
    This can be useful if the fitter wants to resume an earier session that was not completely successful.
  • retrieve <session_id>
    Fetch 1st and last recording of a session from the database and send images, results and notes.
    The notes (product, product_label, notes) will be packed as additional keys to the result objects.
    
• recording <subcommand> ...
  Commands concerning a recording
  The subcommands
  
  • store 1|2 [<infos>]
    Store last recording results (pressure values and analysis results) from the given channel
    The optional <infos> is a JSON object string with the keys 'product', 'product_label' and 'notes'.
    If the recording was already stored only the infos will be updated.
  • cancel [1|2]
    Cancel last recording(s)
    Cancels recording 1 or recording 2 respectively. If no recording is specified both recordings will be cancelled.
    This is useful if the user explicitly wants to cancel a recording before starting a new one. To implicitly cancel an unstored recording use the -force option of the record command.
  • retrieve <recording_id> [1|2|3]
    Fetch recording with <recording_id> from the database.
    The notes (product, product_label, notes) will be packed as additional keys to the result object.
    
    • If a channel is given, the image and the results are for that channel.
      If the destination channel holds an unstored recording an error message will be returned. Use record cancel or record store to clear this problem.
    • If no channel is given, the image will be created in "session compare mode", i.e. the (red) maximum shows the maxiumum pressure of the whole session.
• analysis {<blocks> [<session_id>] | <analyses>}
  Storing and retrieving unique¹⁾ analysis results during a session
  These results may come from measurements or may be results of an inquiry. There are the following types (blocks) of results:
  (¹⁾ unique within a session)
  

  block	contains
  sitbones	Result of sitbone analysis
  	(currently of visual analysis of sitbones pressure image)
  anamnesis	Result of anamnesis
  	(see get appquestions)
  x1	1st result set defined by client application
  x2	2nd result set ...
  ...	(numbering 1 ...)

  The complete syntax is as follows:
  analysis {<blocks> [<session_id>] | <analyses>}
  

  <blocks>:	JSON-array containing the block codes for retrieve
  <session_id>:	... the results belong to
  	(Default is the active session.)
  <analyses>:	JSON-object containing all the results to be stored

• (get mask ...)
• (get appquestions ...)

A series of the commands documented above apply to settings that define the appearance of pressure images. These settings will be stored in the Velobox when disconnecting from the application and they will be retrieved at the next application start.
The client application developer may want to offer menu like graphical elements to the user to let him set everything according to his own flavor. To initialize them the current settings can be obtained using the command get appsettings.
The application responds with a wsevent "appsettings" with a settings object as value of the key appsettings. This object has the keys listed as "Settings" in the following table. If a setting applies to different displays (0 live image; 1, 2 integrated images; 3 other images) there are subkeys 0...3.

Hints to client application developers

Creating JPEG images is the most CPU power consuming part of the whole application. Therefore you should choose your JPEG settings in a way that minimizes power consumption. It is very easy to create an overload situation by setting 'set jpeg 0 resolution 50' for example. You will see a delayed live image and after a few seconds an overload wsevent will arrive. Among the additional information is the temperature. This is because the cpu slows down at high temperatures¹⁾. If at overload the current frequency is lower than the maximum frequency a high temperature might be the reason. It could a good idea to send a warning to your user in this case.
¹⁾It also slows down at low load which would contradict the overload condition.

The pelvis rotation area in real life is very small. (The fitting goal is a minimized area.) Showing the shape with four splines usually only makes sense in a magnified representation.

Bluetooth connection handling is managed by only two commands, btconnect and btdisconnect. In case of an error it's sufficient to rety btconnect after giving an appropriate to the user. In case of ambiguity a menu with all choices should be offered.

Fetching JPEG-Images

An image announced by a wsevent must be either fetched by a HTTP-request or it can be ignored. The URL for fetching is

Notes for the limited experimental Version(s)

DATE:

Changes since Sept 30. 2022:

DATE: Sept 30. 2022

Changes since August 19. 2022:

• -force option in record command

August 19. 2022

Changes since June 15. 2022:

• New command "status"
• Bluetooth implemented

July 15. 2022

Changes since June 13. 2022:

• Missing 'height' in result.pelvisrotation added
• Description of result added in HTML-Doc

July 13. 2022

Changes since June 6. 2022:

• Integrated images are really integrated
• Compare mode works (already during integration)
• New wsevent "ttychange"
• New wsevent "ttystate"
• After recording the real results will be sent.
• New subcommand "record cancel"
• New subcommand "jpeg set quality"
• New command "version"
• New wsevent "overload"

June 6. 2022:

The following limitations must be eliminated until Eurobike:

• record ... returns a dummy result.
• Compare mode is not implemented.
• The "integrated" images in truth are live images.
• Bluetooth connection is not implemented.

The application server listens on Port 8080. In the final Version there will be an apache2-proxy listening on port 80.

There is a very simple HTML test page at http://<velobox-name>.local:8080/test/satteldruckanalyse.html.

Command usage as Tk-Application replacement

The listing below the screenshot indicates the way how commands from the Tk-Application can be implemented with the Velobox API. The table following shows where to place the individual results.

• Select a mask
  set mask nomask|standard|large|custom
• Mask editor
  Mask editor must be implemented by client.
  set mask <pattern>
• Recording time
  Used with record <recording time>
• Max.
  Will be sent by websocket server as a value between 0 and 100% on every change >= 5%.
• Comparison
  set compare ...
• Contrast
  set jpeg colorcontrast ...
• Start recording
  record ...
• Start recording after <delay> s
  Delay must be implemented by client.
• Progress bar must be implemented by client.
• Store pressure image
  recording store ...
• Export pressure flow as JPEG
  Use JPEG-Data fetched from http://<velobox-name>.local/sattelbild?image=sda_...
• Export whole picture as EPS
  Must be implemented by client. (for the time being)
• Load pressure image
  recording retrieve ... session retrieve ...
• Grid
  set jpeg 1|2 grid no|dotted
• Mask
  set jpeg 1|2 mask show|hide