================================== Using the Visionect Software Suite ================================== .. _network-manager-admin: Visionect Software Suite provides a graphical administration interface for managing your server deployment. Log into the Software Suite on port ``8081`` of your server (``http://your_server:8081/``). If it's not, check your networking configuration (see: :doc:`NetworkSecurity`). The default login username is **admin** and the password is set on the first login. We recommend that you change the password immediately after your first log-in. .. _vss_status: ------ Landing page ------------ The index page (the ‘Status’ sub-menu) provides an overview of the installation, such as the number of online devices, the Software Suite version, and a list of registered :ref:`what-is-engine` services along with their system load. .. figure:: images/status.png :align: center *Visionect Software Suite administration interface* | | The **Server Info** label lists the version of the Visionect Software Suite that is running. .. figure:: images/status_info.png :align: center *Server info label* | | The **Engine Load** consists of two parts: average and deviation. The average load displays the average load of the server’s processor cores in the last 1 minute (for example, an average load would be ‘1’ if there exists a 100% load on a single core) and is caused by active tasks. The deviation is the difference between the 1-minute and 15-minute average load caused by active tasks. The label has three levels of severity: - **Green**: load is lower or equals 0.8 (normal) - **Orange**: load is between 0.8 and 1.2 (tolerable) - **Red**: load is over 1.2 (critical) .. figure:: images/status_load.png :align: center *Engine load label on three different scenarios* | | The **Online Devices / Active Sessions** label displays the current number of online and registered devices and active sessions, the maximum value of which is set in ‘Settings’. If we are providing cloud hosting for your devices, the maximum will be the number of paid licenses. .. figure:: images/status_devices.png :align: center *Online devices and active sessions labels* | | The **Firmware Server** label shows the status of the firmware server as configured in the settings menu. The label has two levels of severity: - **Green**: server is online - **Red**: server is offline or the URL is incorrect .. figure:: images/status_firmware.png :align: center *Firmware server status on two different scenarios* | | The **Online Devices** section shows up to 12 online devices. It serves as a shortcut to the online devices sub-menu, with a live view already built-in. .. figure:: images/status.png :align: center *Online devices shown under online devices section* .. _visionect_server_managing_devices: ------ Managing a client device ------------------------ All devices that connect to the Visionect Software Suite store their own data (device status, configuration, and the device’s session) in the :ref:`Network Manager `. The device list can be sorted by name/UUID, battery level (%), state, signal strength, connection type, firmware, or hardware revision. A client device can be in one of the following states: - Online - Offline - Flashing - Flashing complete - Sleeping - Charging - Unavailable - Sending - Receiving The current device status is displayed in the Devices sub-menu. .. figure:: images/devices.png :align: center *List of devices* A device can be configured in the ways: the settings used often are accessible in the Basic mode, while the Advanced mode offers additional settings. ------ .. _basic_mode: Basic mode ~~~~~~~~~~ .. figure:: images/basic_explain.png :align: center *Basic settings for the device* The Basic mode provides a shortcut to the most used settings and the most important information about a particular client device: - Section 1: Device status. The green checkmark indicates that the device is online and the red X that it is offline. - Section 2: Device ID and user-friendly name. - Section 3: Battery and connectivity information. - Section 4: Live view of what is shown on screen, which can be expanded. - Section 5: Device settings, such as display orientation, the content displayed, and use analytics. | | **Device Settings** *Device content* .. figure:: images/basic_content.png :align: center *Under the ‘Device content’ section, the user can change the image that is displayed on the client device.* | - **1. Display web page** .. figure:: images/basic_content_webpage.png :align: center *Display the content of a web page by adding a URL. Link selection is made easier by the input box, which behaves as a search bar. To commit your changes, click the Save button.* | - **2. Upload image** .. figure:: images/basic_content_image.png :align: center *In the ‘Display image’ section, a user can upload a custom image to be shown on the client device. Click ‘Upload’ and select your file.* *The image should be in the .jpg or .png format and will be fitted to match the dimensions of the device display.* | - **3. Add to gallery** .. figure:: images/basic_content_gallery.png :align: center *The ‘Device content’ section also supports the option of rotating multiple images. The images to be shown on the screen are selected among the images uploaded to the gallery.* | - Section 1: Upload images to the gallery. Click ‘Upload’ and select your files. Images should be in the .jpg or .png format and will be fitted to match the dimensions of the device display. All images added to ‘Display an image’ will be automatically added to the gallery. - Section 2: Set the image rotation interval by selecting the number of seconds an individual image is to be shown on screen. - Section 3: Select the individual images to be rotated on the screen. All images uploaded to the gallery are automatically set to appear on the device, as indicated by the green circle showing their position in the rotation sequence. Click on an image to remove it from the rotation sequence, or delete it by clicking on the red trash icon that appears. - Section 4: Select all images in the gallery for rotation. | *Change display orientation* .. figure:: images/basic_orientation.png :align: center | To change the display orientation of your device, choose between: - Landscape - Portrait, 90° - Landscape, 180° - Portrait, 270° Select your preferred option and click Save. | *See analytic* Redirects the user to the :ref:`Charts section ` in Advanced mode, where an overview of device functionality is available. *Device info* .. figure:: images/basic_info.png :align: center | Device info contains key information about the client device such as device type, firmware version, and display type. | *Refresh content* By selecting Refresh content, the image shown on the client device will refresh to reflect any changes since the last device content sync. ------ .. _advanced_mode: Advanced mode ~~~~~~~~~~~~~ The Advanced mode allows for more complex settings of your devices. Choose between: - `Status & Settings`_: change the different settings of the selected device, or flash it with new firmware. - `Device configuration`_: open advanced device configuration for any connected device. - `Live view`_: see what is currently displayed on a particular device or check a session that might not yet be deployed. - `Charts`_: see performance analytics charts for an individual device. - `Events`_: see the disconnects, reboots, displayed images, etc. that occurred while a device was connected. .. figure:: images/devices_tabs.png :align: center *Advanced mode tabs* | .. _advanced_status_and_settings: Status & Settings ^^^^^^^^^^^^^^^^^ The ‘Status & Settings’ tab offers a comprehensive overview of device settings: .. figure:: images/ss1.png :align: center *Status & Settings in advanced mode* | - 1. Status: The current state of the device - online or offline. - 2. Name: A field to set a user-friendly name for the device to be displayed in front of the device ID. - 3. Firmware Revision: The firmware version running on the device. The ‘Change’ checkbox allows the user to manually set the firmware version. - 4. Sleep > Period: Choose between three options of sleep management or disable sleep altogether. Find out more :ref:`here ` - 5. Automatic update to latest firmware: When checked, the device firmware will be automatically updated when a new version is available. - 6. Automatic update to latest bootloader; When checked, the device bootloader will be automatically updated when a new version is available. .. figure:: images/ss2.png :align: center *Status & Settings in advanced mode* | - 7. Backend: Choose between two options: HTML or HTTP. - 8. Default dithering: Choose between Bayer or Floyd-Steinberg dithering. To disable all dithering algorithms, choose None. - 9. Default bit depth: Choose between 1 or 4-bit depth. - 10. Display type: The electronic paper display used on the client device. Choose the Custom option to manually set the desired display parameters. - 11. Enable image optimization: Automatically adjust certain image properties such as contrast for optimal results. Not applicable on colour displays. - 12. Enable intelligent updates: Update the device screen only in the area of the display that has changed content. | .. _device_configuration: Device configuration ^^^^^^^^^^^^^^^^^^^^ The Visionect Software Suite provides the capability to configure all aspects of device operation remotely. Choose a client device from the list and select the ‘Device configuration’ tab. .. figure:: images/devices_config.png :align: center *The device configuration pane of the Visionect Software Suite.* ‘Read from device’ will load the current settings on the device. The settings are separated into various categories, with ‘Basic’ shown by default. ‘All’ will show all the settings. Make sure you commit your changes with ‘Write to device’. .. warning:: The device configurator is a very powerful tool that enables you to configure low-level settings which will impact how a client device works. **In some cases, you could permanently damage the device.** Please consult the explanation in ‘?’ (question mark) if you’re not sure what a setting does. Alternative ways of configuring your client device are: - With your application, via the :ref:`JavaScript API `. - With the Visionect Configurator, through the :doc:`advanced command line interface `. | Live view ^^^^^^^^^ The Live View tab shows the content displayed on the device in real-time. This is particularly useful in cases where a device is not immediately available. .. figure:: images/devices_liveview.png :align: center *Live view feature* | .. _charts: Charts ^^^^^^ See device behaviour over time – everything from battery performance to signal strength and disconnects, for exactly the time span you have set, analyzing the performance of devices over time. .. figure:: images/devices_charts.png :align: center *Charts example* | Events ^^^^^^ Keep track of important device events over time for the time span you have set - connection errors, full logs, wake-ups, reboots, and more. .. figure:: images/devices_events.png :align: center *Events example* The ‘Device management’ buttons at the bottom of the ‘Devices’ page manipulate the selected devices: - Pressing the **Remove device** will remove the device from the database - Pressing on the **Reboot device** button will cause all the selected devices to reboot. The time it takes for the devices to reboot can vary. - Pressing on the **Restart session** button will cause a restart of WebKit services for all the selected devices, which means that the page will be reloaded. - Pressing on the **Clear web cache** button will clear the session’s WebKit cache. - The **Enable debugging** button, when clicked, will initialize a debugging session for the selected device. A link will appear on the page with the URL of the debugging session. The URL provides a web inspection tool for the selected device, which means the developer has full access to the live device session and the HTML rendering backend, and the API functions. For example, calling ``console.out(okular.device_uuid);`` will print the device’s UUID to the console window. .. figure:: images/devices_buttons.png :align: center *Device management buttons* | .. note:: The ‘Clear web cache feature’ is only relevant if the device is using the HTML rendering backend. .. note:: The debugging feature might not work on hosted server instances due to firewall settings. For testing purposes, it is recommended to use a local Virtual Machine or Docker image instead. .. _Google Chrome: http://www.google.com/chrome/ .. _Apple Safari: https://www.apple.com/safari/ .. _Epiphany: https://wiki.gnome.org/Apps/Web .. note:: The ‘Enable debugging’ feature only works if you are browsing the web inspection URL with a WebKit-based browser, like `Google Chrome`_ , `Apple Safari`_, or `Epiphany`_ .The inspector does not work on Firefox browsers. .. _sleep-manager: ------ Device power management and Sleep Manager ----------------------------------------- Device power consumption, and consequently battery life, can be significantly reduced by turning the device off (i.e. sending it into sleep mode) for the time period in which the display content does not need to be changed. While the device is in sleep mode, its screen will continue showing the last image displayed. .. warning:: While in sleep mode, devices will rely on an internal clock and it is not possible to wake them up remotely. The Visionect Software Suite provides a Sleep Manager feature that implements basic usage of the sleep feature. Three options of sleep options are listed: - Periodical: the client device will go to sleep periodically, at time interval set. - At time: the client device will go to sleep at a certain time of day - Working hours: the client device will go to sleep outside of the working hours set. .. note:: In the case of high-grained control requirements the sleep feature can be also controlled directly from JavaScript. To activate the Sleep Manager feature, go under ``Settings ->Global-> Features`` in the Visionect Software Suite and check the ‘Sleep Manager’ box. .. figure:: images/settings_sleep_enable.png :align: center *Enabling the Sleep Manager in the Global settings* In the Devices sub-menu of the Visionect Software Suite (under ``Devices -> Status & Settings``) you’ll see the sleep segment. Setting a time will enable sleep management from the Software Suite: the device will be in sleep mode until it reaches the predetermined time of day. If you require the device to wake up periodically, say, every 30 minutes, then set the time to 00:30 and Periodical to yes. The device will display the first picture immediately after connecting to the Suite, then it will switch into sleep mode, and from that point on it will wake up every half hour. **Usage example:** A user sets the Sleep Manager on ‘Periodical: Yes’ and ‘Time: 0:30’ and saves the settings at 9:12 am. The first picture will be displayed in 1-2 minutes, then the client device will go to sleep and wake up (sending a new picture) at 9:30 am, after that at 10 am, then 10:30 am, and so on. .. figure:: images/MI_sleep.gif :align: center *Sleep configuration in device pane* .. note:: The clock will drift between devices due to temperature fluctuations and in 24hrs you can expect a difference of +/- 10 minutes in wakeup times in the group. The sleep mode greatly impacts the power consumption of your device. For more details on this topic, check :doc:`power consumption documentation `. ------ Apps ---- Any HTML-based web page can become a Visionect Software Suite application. Simply add the URL to the list of applications. The Visionect Software Suite will run the page using an industry-standard Webkit rendering engine, making most contents render as is out of the box. For the best performance, you’ll need to adapt the content to the limitations of the display medium. The Apps section provides a list of the available web apps which can be selected from the Application drop-down in the Devices section of the Software Suite (for each selected device). By clicking the ‘Add new’ button at the bottom, a new row is added with entries for the app name, its URL, and a short description. **Usage example:** .. figure:: images/app.gif :align: center *Adding new app* .. note:: Every change to existing Apps or every newly created App must be saved. If there are no apps defined, the default URI is used from the global settings. .. _server-settings: ------ Settings -------- This is where you reconfigure how the Visionect Software Suite works. .. figure:: images/settings.png :align: center *The Settings menu in the Visionect Software Suite* Important configuration considerations are: Display options, rendering and ghosting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the Visionect Software Suite’s graphical engine will draw an inverse image before rendering the target image. This is done to reduce the ghosting effect on the screen occurring due to the nature of e-paper displays. The server configuration flags that configure the way the screen is updated can be found under ‘Display options settings’. - *Clear screen* - clears the screen with a white image before rendering the target image. If you are doing partial updates, please note that the ‘Clear screen’ will wipe all display content. - *Display border* - controls whether a border should be drawn on the edge of the screen. Setting to 'Draw black border' will draw a black border, 'Draw white border' draws a white border, and 'Disable device border' will not draw any borders (the default option). - *Disable inverse updates* - inverts the update before rendering the target image, removing ghosting at the cost of the update speed and flickering. This works well with partial updates (only the target region will be updated). It is also possible to deal with image inverse feature directly in your app with the help of JavaScript (:ref:`see Rendering performance and optimizations `). .. warning:: Some of the rendering-related settings might not work correctly on older-generation devices running very outdated firmware. Please contact our support at `support@visionect.com `_ for more details. Setting the maximum number of active sessions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You limit the number of active sessions (i.e. how many sessions can be spawned by the Suite) by setting the ‘Max Sessions’ value. Observe the current status in the ‘Status’ sub-menu of the Visionect Software Suite (Active session / Maximum). When the number of active sessions reaches the limit, this prevents any new session from being created. For cleaning the old (unused) sessions, it might be necessary to restart services. Users should set the limit carefully, as it is related to the available memory of your server (more active sessions require more RAM). Other important settings ~~~~~~~~~~~~~~~~~~~~~~~~ **Global** - Deployment Name: the name of the deployment. - Deployment Key: a unique identifier for the current Visionect Software Suite installation. It is generated automatically upon installation. - Timezone: the custom timezone drop-down menu. **Graphics Engine** - Default Backend: choose either the HTML or HTTP backend as the default. - Max Sessions: sets the maximum number of sessions available to the HTML rendering engine. New session requests will be ignored if the number exceeds the limit. - Image Cache Size: set the maximum size in MB of the image cache. - Idle Threshold: sets the time in minutes after which an idle session is destroyed. **HTML Backend** - Default URL: sets the URL of the default application. - Automatic page reload: sets the time in seconds in which the page will reload. Setting the value to 0 will disable the automatic page reload. - Web Session Memory Limit: sets the memory limit in MB that, when hit, will result in the Visionect Software Suite restarting each WebKit process to protect against memory leaks. - User Agent: sets the custom string to the user agent for identification - Render Timeout: how long the HTML rendering engine (formerly known as Okular) should wait for a rectangle region (in milliseconds) to be rendered before preprocessing the data for the device. Longer intervals are usually needed for rectangles with complex graphics, or if running an HTML rendering engine on a slow machine, - Enable Font Antialias: configures if the fonts displayed on the device should be anti-aliased by the standard GTK+ anti-aliasing process. Set to ‘disabled’ if you’re using pixel-perfect fonts. - Enable Page Caching: sets if the loaded pages and resources should be cached or not. **Default Device Settings** - Ignore Input I Device Not in Sync: ignores any new click requests from the client device in case there is unsent data in the device session. This means new clicks won’t affect the application and the old response will be sent instead, - Bit Depth: configures the default display bit depth. Valid values are 1 and 4. The 1-bit encoding reduces the refresh rate to 250 ms (the limitation of electronic paper technology), while 4-bit is the maximum bit depth. This value can be overridden by the HTML rendering backend (formerly known as Okular) Javascript Extensions in the web application, - Display Rotation: sets the default display rotation. Values are given in degrees and cover all four layouts. - Dithering: every web page has to be converted from color to grayscale or black and white (according to the Graphics Engine setting). You can choose the type of dithering based on performance and quality requirements. Currently supported (in order of quality): none, Bayer and Floyd-Steinberg. Noise dithers will not be supported, as they negate the Graphics Engine render caching infrastructure. - Force Rectangle Support: Enables a partial screen update. - Force Group Synchronization: enables or disables the virtual screen synchronization. - Synchronize groups only if all of its devices are present: enables virtual screen synchronization only if all of the client devices are present. - Automatic Firmware Upgrade: automatically updates all new client devices with the newest firmware. - Automatic Bootloader Upgrade: automatically updates all new client devices with the newest bootloader. - Device State Polling: sets the time in minutes in which the Visionect Software Suite queries the device for its status. **Firmware** - Firmware Repository: sets the default URL for a firmware repository server. ------ Users and API Keys ------------------ By default, there's always a default user **admin** and the password is set by the user on the first login. To add a new user, click on ‘Add new user’ and type in the new username and password. To activate the user you must also tick the ‘Enabled’ checkbox, as disabled users are not permitted to log in. If you want to use the management features programmatically, you will need to create a new API key that your applications will use to access our servers. For more information on the management API and instructions on how to use the generated user/API secret, please consult the `Visionect Software Suite API `_.