Active Citizen Research (ACR)

How can technologies enable citizens to have an active role in research?

This project aims to explore this question through the design of two hardware
prototypes and accompanying software, which is split into three software components:

1. Server: website to acquire new participants using their perceived or desired skills
   for comparative analysis and matchmaking.
2. Server: REST web service to mediate and store messages between users.
3. Client: bespoke software for direct audio communication between prototypes.

The technology design choices were directed from a previous workshop held with three
citizens and researchers that explored the potential of technologies to broker a
citizen’s local community knowledge and skills to further an area of research to them.

Features

The core features of the client are assigned to an individual button on each artefact:

• record: record an audio and send it to the current matched user
• play: plays an audio message for the current matched user.
• next: plays the next audio message in a conversation.
• previous: plays the previous audio message from a matched user.
• users: switches between matched users if there are matches. All other features
  reflect this change, e.g. play will play for the current matched user.
• notify: flashes LEDs to notify the user of a change: matched users, recording
  audio, and message sent.

Note: once client.py is run, it will check every 5 minutes for new messages and matches.

The server hosts the website for participants to get involved (i.e. sign-up), and the
REST web service used by the client codebase:

• Website: responsive, mobile first website to recruit new participants.
• Matchmaking: proof-of-concept algorithm that matches citizens to researchers based
  on the citizen’s skills and the researchers desired skills for a project.
• REST API: enables a client to obtain messages for a given conversation and new matches.
  • upload: enables a user to send another user an audio message.
  • download: enables a user to download all unread audio messages in a conversation.
  • matches: finds all the matched users for a given user.

Technologies used

• Server codebase

  • Python Flask framework to power the back-end
  • Flask-SQLAlchemy for storage and
    ORM to simplify database access
  • Requests to create a REST service for audio access and transmission
  • Bootstrap Freelancer
    heavily modified theme for sign-up website

• Client codebase

  • RPIO to invoke Python methods when
    specific buttons have been pressed on a raspberry Pi
  • Requests to access the REST service
  • Bespoke software
    interacting with the REST service to provides core features to each PI

Repository structure

This repository hosts the codebase for the client (audio communication between devices) and
server (REST service & website).

• run.py
  • Starts the web server when invoked
• matchmaking.py
  • An algorithm that is invoked nightly to match un-matched users and notify them.
• app/
  • /static/
    • The css/javascript/images used by the website
  • /templates/
    • The markup files used to create the frontend
  • _init_.py
    • Used to initialise the Flask application
  • api.py
    • The REST API for client interactions (upload/download/matching)
  • models.py
    • Database representation for the ORM
  • views.py
    • Delivers web-pages (templates) for given requests. Stores user details to database.
• client/
  • client.py
    • An independent script that provides audio communication functionality for devices
  • loader.sh
    • A shell script to run the client code upon Raspberry Pi - via a cron job.

Installation — local development

Create a virtualenv to
install the dependencies required to run the server:

virtualenv venv
source venv/bin/activate
pip install -r requirements.txt

Note: the client codebase requires RPIO GPIO toolbox
to be installed on the Raspberry PI machine as it is not provided as a requirement —
the server and API exist regardless of client codebase.

Viewing the website

You can view the website locally at http://127.0.0.1:8080/ by running the
flask app:

python run.py

This creates the Flask application, which the REST API is hosted.
Establishing a server is required before running the client codebase.

Running the client code

To run the client code a client must first be matched, and you must have two instances and
hardware to validate a bi-directional conversation. To ease development, pop.py was written
that automatically creates the database and initial message. This should be run once:

python pop.py

The client code can now be run. By default, you would have been matched with rem. You can
then send messages to the matched user through your custom hardware (or our artefact).

Validating messages sent

Modify the api_key in clients.py to rem — the person you just sent messages to.
If you run the client script again you can now playback all the audio’s you sent.

Network configuration

To make the website externally visible
modify the host address in run.py to 0.0.0.0, which opens the server for access on the local network
(Intranet) through the IP address of the server. You then need to (1) find the IP address of the server
and (2) manually update client.py to point to this address. To do that:

1) run ifconfig and make note of the inet of etho0. This is the IP
address of the machine you are running the server on.
2) update client.py to point to your server
3) ensure that both the server and client are on the same network that has port 8080 open
(this would not work on a university network, but would work at home or OL-Kitchen-WIFI)