.. docs/source/user_client/client_installation.rst
.. Copyright (C) 2012, University of Cambridge, Department of Psychiatry.
Created by Rudolf Cardinal (rnc1001@cam.ac.uk).
.
This file is part of CamCOPS.
.
CamCOPS is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.
CamCOPS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
.
You should have received a copy of the GNU General Public License
along with CamCOPS. If not, see .
.. include:: include_tabletdefs.rst
Installing and configuring the client
=====================================
.. contents::
:local:
:depth: 3
Hardware and operating system requirements
------------------------------------------
See :ref:`hardware_requirements_client`.
.. _client_installation:
CamCOPS client installation
---------------------------
Android
~~~~~~~
Install the Android app directly from the Google Play Store:
- https://play.google.com/store/apps/details?id=org.camcops.camcops
Android: manual installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**This method is now deprecated. Use the Google Play Store method instead.**
Manual installation of an Android package is possible like this:
#. Ensure your Android device permits the installation of third-party apps:
e.g. :menuselection:`Settings --> Security --> Unknown sources (Allow
installation of apps from unknown sources)`.
#. Download and install the CamCOPS client (see :ref:`download `) as
an .APK (Android Package Kit) file.
iOS
~~~
Install the iOS app directly from the Apple App Store:
- https://www.apple.com/uk/ios/app-store/
Windows
~~~~~~~
Download the Windows application from the CamCOPS :ref:`download `
page.
If you have trouble see :ref:`client troubleshooting `.
Under Windows 10, you may see the warning:
.. code-block:: none
Windows protected your PC
Windows Defender SmartScreen prevented an unrecognised app from
starting. Running this app might put your PC at risk.
[ More info ]
[ Don't run ]
Choose "More info" then "Run anyway".
If it says
.. code-block:: none
User Account Control
Do you want to allow this app from an
unknown publisher to make changes to your
device?
camcops_2.2.7_windows.exe [or similar]
...
then choose "Yes".
Linux
~~~~~
.. todo:: Package CamCOPS client for easier Linux distribution.
.. _configure_client:
Launching the CamCOPS client
----------------------------
Launch the app in the normal way. For Windows, run it from the desktop shortcut
or the Start menu. For Android, launch it from the Apps screen.
Advanced launch options
~~~~~~~~~~~~~~~~~~~~~~~
In operating systems that allow you to launch applications with options (e.g.
Windows, Linux), there are some additional advanced options offered, as
follows.
Options:
.. literalinclude:: _camcops_client_help.txt
:language: none
.. _client_nonstandard_db_location:
*Specifying a non-standard database location*
By default, the CamCOPS client stores its encrypted databases in the "user
data" area; see :ref:`Where does the client store my data?
` You can use the ``--dbdir`` option (see above)
to change this. This is an **advanced** option. You cannot change the filenames
of the databases, which are fixed to ``camcops_data.sqlite`` and
``camcops_sys.sqlite``.
Clinician vs single user mode
-----------------------------
The CamCOPS app has two modes of operation. You select the mode when you start
CamCOPS.
When in Clinician Mode, you have full access to all settings and tasks (subject
to copyright restrictions).
:ref:`Single User Mode ` is designed for a patient using the
app at home on their own tablet and offers a much simpler user interface. Only
those tasks that appear in the patient's :ref:`task schedule
` are available.
Terminology: usernames and passwords in CamCOPS
-----------------------------------------------
.. note::
We will often refer to the client as a “tablet”, because it often is, but
it might equally be your laptop or desktop running Windows/Linux/OS X.
In a low-security environment, you’ll be your own administrator. In a
high-security environment, we’ll distinguish the user (“clinician” or “patient“) from the
technical security person (“administrator”).
CamCOPS uses the following usernames and passwords:
- **TABLET PASSWORD.** Your tablet will need a password to unlock it. This is
nothing to do with CamCOPS.
- **CAMCOPS APP PASSWORD.** The CamCOPS application will also need a password
to unlock it. Without this, no access to CamCOPS encrypted data is possible.
- **CAMCOPS PRIVILEGED-MODE PASSWORD.** This password unlocks the deep dark
secrets of the app. Whoever has this can, for example, change the server that
the app sends its data to. In a high-security environment, this password is
typically known to the administrator, but not the clinician.
- **CAMCOPS SERVER USERNAME** and **CAMCOPS SERVER PASSWORD.** These
authenticate a user (who might be a clinician or an administrator) to the web
interface, hosted by the CamCOPS server. You will use this username/password
combination to (a) log in to the web site, and (b) upload data from your
tablet, or register the tablet with the server. In more detail:
- The CamCOPS app needs to know a username/password combination to register
with a new server. (Registration is typically done by the administrator
using their username/password.)
- The CamCOPS app needs to know a username/password combination to upload
data to the server. (Uploading is typically done by the clinician using
their username/password. The app may or may not be allowed to store the
password — that’s a local security policy decision — but it will store the
username.)
- When operating in :ref:`Single User Mode `, where the
CamCOPS app user is typically a patient using the app on their own tablet,
the username and password are generated automatically. First of all the
administrator creates a patient record on the server and this includes a
unique key, which is shared with the patient. When the patient starts the
app for the first time, they register themselves and their device with the
server by entering this key. At this point the server creates a username and
password and these are stored on the tablet.
- You will type in your username and password to access the CamCOPS web
viewer. This interface is used to view tasks that have been uploaded from
tablets. Administrators can also use this interface to create or edit
authorized users.
Configuring your tablet before using CamCOPS
--------------------------------------------
This section has nothing specifically to do with CamCOPS, but describes general
good security measures to take (or measures that your institution may oblige
you to take) with any mobile device holding sensitive information.
iPad
~~~~
- Set up appropriate security on your tablet. For a research environment with
no patient-identifiable data, this may involve no work. But for a secure
environment:
- :menuselection:`Home --> Settings --> General --> Passcode Lock`
- :menuselection:`... --> Simple passcode = OFF`. Why? Because 4-digit
passcodes are weak; use a strong password [#passwordstrength]_, and don’t
forget it! We’ll call this the TABLET PASSWORD.
- :menuselection:`... --> Turn passcode on`
- :menuselection:`... --> Require passcode = immediately`
- :menuselection:`... --> Erase data = ON` (which will erase all data on
the iPad after 10 failed passcode attempts).
- Setting a passcode lock automatically encrypts data on the iPad
[#iossetpasswordencryptsdata]_ [#ioskeychainvulnerable]_.
- Install CamCOPS; see :ref:`above `.
Android
~~~~~~~
- Set up appropriate security on your tablet. For a research environment with
no patient-identifiable data, this may involve no work. But for a secure
environment:
- Plug in the tablet; charge its battery fully. (Encryption takes a while and
requires a charged tablet that’s plugged in.)
- :menuselection:`Settings --> Security --> Screen lock --> Password`
- Enter a strong password [#passwordstrength]_, and don’t forget it! We’ll
call this the TABLET PASSWORD.
- :menuselection:`Settings --> Security --> Encryption --> Encrypt tablet -->
Encrypt tablet` ... which may take a while.
- Install CamCOPS; see :ref:`above `.
.. _configuring_client:
Configuring CamCOPS before using it
-----------------------------------
**Using the CamCOPS server’s web interface, the administrator should:**
- Create a username and password for the new user.
- Add that user to one or more :ref:`groups `.
- For each group, edit the user’s group permissions. Normal settings:
- *Permitted to upload from a tablet/device.* Almost certainly YES.
- *Permitted to register tablet/client devices.* May be NO in very high
security environments (in which case the administrator will have to use the
tablet to register it on behalf of the final user); YES is more convenient.
- *May log in to web front end* YES if the user needs access to any of the
below functions of the admin interface. Otherwise NO.
- *May add, edit or delete patients created on the server.* YES if the user
needs this function, otherwise NO. See :ref:`Manage patients and their tasks
`.
- *May send emails to patients created on the server.* YES if the user needs
this function, otherwise NO. See :ref:`Manage patients and their tasks
`.
- *May view (browse) records from all patients when no patient filter set.*
Almost certainly NO, for confidentiality reasons.
- *May perform bulk data dumps.* YES for researchers needing this function;
otherwise NO.
- *May run reports.* Reports cover a mixture of administrative and
patient-finding functions. If in doubt, choose NO.
- *May add special notes to tasks.* Likely to be YES for senior users.
- *User is a privileged group administrator for this group.* Usually NO.
If you say yes, the user will be able to create new users and manage this
group.
- If you intend to run the app in :ref:`Single User Mode `,
you will need to create patients and :ref:`schedule tasks `
for them.
**On the tablet, when operating in Clinican Mode, the administrator should:**
#. Touch the padlock (top right) to unlock. (The first time CamCOPS is run,
there will be no lock passwords; you need to set them, as below.)
#. :menuselection:`Settings --> Set privileged mode (for items marked †)` (the
icon at the top right will now show a golden pair of padlocks).
#. :menuselection:`Settings --> (†) Change privileged-mode password.` Enter a
password for this tablet; do NOT tell the clinician; keep it in your
Administrator’s Safe.
#. :menuselection:`Settings --> Change app password.` Enter a starting password
for the clinician (their CAMCOPS APP PASSWORD); tell the clinician what this
is.
#. :menuselection:`Settings --> (†) Configure server settings`.
- Set the server hostname
- Set the server path
- Ensure “Validate SSL certificates?” is set to “Yes”.
- Choose the “Store user’s server password?” option. Your users will
probably thank you for choosing “Yes”. The especially security-conscious
may want “No”. (This setting determines whether the tablet will store an
encrypted version of the user’s password; it allows the user to unlock
CamCOPS with their CamCOPS app password, but then not to have to re-enter
their CamCOPS server password each time they upload.)
- Other values can typically be left as the default.
- Save those settings.
#. Assuming you will not allow the user to register devices with the server,
you’ll have to do it yourself:
#. :menuselection:`Settings --> User settings --> Username on server.`
Enter your administrative CAMCOPS SERVER USERNAME. (Don’t enter a
password here, even if you allow users to store their password; you don’t
want your administrator’s password saved.)
#. Save those settings.
#. :menuselection:`Settings --> (†) Register this device with the server.`
(It will ask for your administrative CAMCOPS SERVER PASSWORD, and then
should initiate communication with the server, and succeed). Until
registration has succeeded, the app will not be able to upload.
#. Optionally, to be nice to the user: :menuselection:`Settings --> User
settings --> Username`; enter the clinician’s CAMCOPS SERVER USERNAME;
save those settings.
#. Ensure you haven’t accidentally stored your administrative password in the
app (:menuselection:`Settings --> User settings`). If you followed the
instructions above, you won’t have done.
#. Touch the padlock until it shows the red, locked icon. You can now give the
tablet to your clinician.
**The clinician should then:**
- If the whole tablet is locked, unlock it with the TABLET PASSWORD.
- Touch the padlock to unlock. You will need your CAMCOPS APP PASSWORD,
supplied to you by your administrator.
- :menuselection:`Settings --> Change app password.` Change the password to a
strong password that you like [#passwordstrength]_. Remember it.
- :menuselection:`Settings --> Intellectual property (IP) permissions.`
Answer all the questions honestly and save your changes.
- :menuselection:`Settings --> User settings.` Set these:
- Device friendly name: e.g. “Joe Smith’s LPS iPad”.
- Username on server: your CAMCOPS SERVER USERNAME, supplied to you by your
administrator.
- *If your administrator has allowed you to store your server password:*
Password on server: your CAMCOPS SERVER PASSWORD, supplied to you by your
administrator.
- Default clinician’s specialty, name, professional registration, post,
contact details: set values that you would typically enter in patients’
notes. For example, a UK doctor might have: specialty = "Liaison
psychiatry"; name = "Dr John Doe"; professional registration = "GMC#
123456"; post = "Consultant"; contact details = "extension 1234; bleep
5678".
.. note::
The clinician’s name that you enter will be automatically processed into
prefix/forename/surname components for HL-7 diagnosis (DG1) segments, if
you use a recognized format. Recognized formats include, for example,
Prefix Forename Surname (where prefix is Dr, Prof, Miss, Mrs, Ms, Mr, Sr,
with or without full stops); Forename Surname; Surname, Forename. If the
software doesn’t recognize the format, it will put the whole name verbatim
into the surname field for DG-1 codes.
Good to go! See :ref:`using the tablet app `.
If your CamCOPS server is upgraded
----------------------------------
Use :menuselection:`Settings --> Fetch all server info` to inform the client of
changes. (This is exactly like client registration, but doesn't require
registration permissions.)
When in :ref:`Single User Mode `, switch first to Clinician
Mode with :menuselection:`More options --> Change operating mode`.
Other CamCOPS app settings (Clinician Mode)
-------------------------------------------
Language
~~~~~~~~
:menuselection:`Settings --> Choose language` |language|
You can choose the language in which CamCOPS operates.
Questionnaire font size and DPI settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:menuselection:`Settings --> Questionnaire font size and DPI settings`. Choose
a font size that you like.
You can also override the system's DPI settings (DPI = dots per inch -- more
strictly, PPI or pixels per inch). You are unlikely to need to change the
logical DPI (and note that getting it wrong can make CamCOPS look dreadful!).
However, some computers do not accurately report their physical DPI. Some
CamCOPS tasks use visual analogue scale (VAS) sliders set to a real physical
length (e.g. 10cm for the :ref:`ORS `). To get these right, CamCOPS needs
to know the physical DPI of your screen. If your computer isn't reporting it
right, you can override the settings here. Changes take effect when CamCOPS is
restarted.
Upload after each task is complete?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:menuselection:`Settings --> User settings --> Offer to upload every time a
task is edited?`
Other tablet settings that can affect CamCOPS
---------------------------------------------
Turn off auditory interruptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If beeps and buzzes from other apps would interfere with your use of CamCOPS,
disable them.
- For Android: :menuselection:`Android Settings --> Sound --> Volume`; then
turn off things like “Ringtone” (for phones), “Notifications”, and “System”.
- For iOS: :menuselection:`iOS Settings --> Notifications`, and turn “Sounds”
off.
===============================================================================
.. rubric:: Footnotes
.. [#passwordstrength]
xkcd *Password Strength:* http://xkcd.com/936/.
.. [#iossetpasswordencryptsdata]
http://support.apple.com/kb/ht4175
.. [#ioskeychainvulnerable]
The iPad's keychain is still vulnerable to attack: see summary at
http://www.maravis.com/ios-device-encryption-not-effective/, or PDF at
http://www.maravis.com/blog/wp-content/uploads/iOS-device-encryption-security.pdf.
However, CamCOPS does not store its passwords in the keychain, and app
storage is separate from the keychain.