In Acts 8 verses 36-39, some woman called Dorcas falls ill and dies, and then rises again. No worshippers for her, just more thankless life. Thanks God! Anyhow, Dorcas is the name of the second incarnation of this stupid talking Creepy Urchin thing at Nottingham Hackspace.

Some time in 2024 it fell ill and died (just like Dorcas - it must be prophesy!). Probably what happened is that it was unplugged or there was a power outage, and then either nobody could figure out how to (or didn’t want to) turn on the crotch-speaker.

Subsequently, the speaker was removed and various random wires and crappy speakers were shoved into the chest cavity in the vain hope it would start working again. The SD card also had bad sectors and the Pi was starting to boot unreliably. The LCD screen had long since been removed by some fiendish parts pilferer.

Poor little Dorcas needs a refit, so here we are.

Version 2.0 of UrchinWare(tm) has some minor changes:

Full re-write - the old code was horrible (Jeeer!):

• Putting data in Sqlite3 rather than hard-coding everything (wowsers!)
• Splitting modules into separate files (zammo!)
• Stripping out the display parts since there is no display (hurrah!)
• Simpler dependencies (no more Qt or need for a display server - huzzah!)
• New features! (zaaaaap!)

Building & Running

1. Install your OS on the device where you want to run this project. The Nottinghack Urchin runs on a RPi 3. At various times the base OS has been Raspbian (lite image) and OpenEuler. Some extra packages must be added over a base install (Raspbian package names here):

   • sox
   • espeak
   • espeak-ng
   • bind9-dnsutils
   • sqlite3
   • pigpiod
   • scanlogd (optional - if you want to be informed of portscans)
   • mosquitto (optional - if you want to run a local MQTT server for testing)

   Run: sudo systemctl enable pigpiod ; sudo systemctl start pigpiod

2. Clone project; create a virtual env and install Python dependencies:

# mkdir /opt
# git clone https://github.com/mousefad/urchinware-2.git /opt/urchin
# cd /opt/urchin
# python -m venv .venv
# . .venv/bin/activate
# pip install --upgrade pip
# pip install .

3. Set a couple of environment variables so the program can find relevant files:

$ export DORCAS_DATABASE=/opt/urchin/db.sqlite3
$ export DORCAS_AUDIO_DIRS=/opt/urchin/audio

4. Generate a config database from the sample, dorcas/sample/db.xml (this file is a GNUmeric spreadsheet for easy viewing/editing). This command will generate the file at the path defined by DORCAS_DATABASE.

# python dorcas/database.py load dorcas/sample/db.xml

5. Run with python -m dorcas --config default

Configuration

The database can store multiple configurations - one per record in the CONFIGS table. Only one configuration can be active when the program is running. The configuration to use can be selected using the --config <id> option when starting the program. If the --config option is not used, the program will select the record where the ID field matches the hostname of the machine where the program is running.

A configuration selects a record from the BROKERS table to decide which MQTT broker to connect to. At time of writing broker certificates are not supported (since the one at Nottingham hackspace is open / unencrypted).

Other tables:

• VOICES - parameters for the espeak text-to-speech engine.
• EFFECTS - post-procesing of speech audio with play (part of SOX).
• IGNORES - patterns of MQTT messages to ignore.
• SPECIAL_DAYS - define holidays and such.
• GREETINGS - generic and personalized greetings.
• MUSINGS - responses to general MQTT events and interctions with DonationBot.

Editing Config With GNUmeric

The sample config database is provided as a GNUmeric spreadsheet in XML format, which is convenient to read and edit using the GNUmeric Free software application. This can then be converted to an SQLite database withthe following command (from the repo root directory):

# python dorcas/database.py load path/to/spreadsheet.xml

The spreadsheet will be converted into an SQLite database which will be saved to the path defined by the DORCAS_DATABASE environment variable.

Editing the spreadsheet and re-generating the SQLite database is a fairly convenient way to work, but you do you - edit that database however you like.

Greetings

Greetings are triggered when someone enters the front door of the hackspace (i.e. the door is opened from the outside with an RFID card).

One Greeting will be selected and the Action performed. Greetings are selected from the GREETINGS table in the database as follows:

1. Select where GREETINGS.MEMBER is NULL or GREETINGS.MEMBER == <member_name>
2. Drop records where GREETINGS.CONDITION is not NULL or the condition evaluates to False (see Conditions, below).
3. From the remaining records select one greeting randomly (weighted by the WEIGHT value).
4. Perform the ACTION (see Actions, below).

Musings

Musings are triggered by sensations. Sensations occur when any MQTT message is seen (with the topic and message from the MQTT message. Some sensations are generated internally (e.g. when Urchin starts up or shuts down, or when Urchin becomes bored).

Every time a sensation is experienced by the Brain, records in the MUSINGS database table are evaluated as followed:

1. Select all records where MUSINGS.TOPIC matches the topic of the Sensation.
2. Drop records where MUSINGS.CONDITION is not NULL or the condition evaulates to False (see Conditions, below).
3. From the remaining records select one musing randomly (weighted by the WEIGHT value).
4. Perform the ACTION (see Actions, below).

Conditions

Greetings and Musings are filtered by Conditions. A condition is a Python expression that evaluates to True or False. Conditions are evaulated with a limited execution context with access only to Brain State Variables and the following functions:

• random() Call Python random.random().
• random_choice(list) Call Python random.choice(list)
• random_int(a, b) Call Python random.randint(a, b).

Actions

Actions are small Python programs that are performed as a consequency of a Greeting or Musing. Actions execute in a limited execution context with access only to Brain State Variables and the following functions:

• eyes(final, duration=0.5) Fade Urchin’s eyes to intensity level final (value between 0.0 and 1.0), taking duration number of seconds to do so. This operation is non-blocking.
• log(message) Print message to diagnostic output with level logging.INFO.
• pause(seconds) Block execution of the action for the specified number of seconds.
• play(file_id, bg=True, volume=1.0) Play an audio file, found under any of the directories defined in the environment variable DORCAS_AUDIO_DIRS (separated by the : character). volume is a floating point value between 0.0 and 1.0. The bg value determines if the play operation blocks or if playing of the audio file is performed in the background.
• publish(topic, message) Publish a message over MQTT with the specified topic and message payload.
• random() Call Python random.random().
• random_choice(list) Call Python random.choice(list)
• random_int(a, b) Call Python random.randint(a, b).
• say(text, voice="default") cause Urchin to say text using voice from VOICES table where ID == voice.

Brain State Variables

Dorcas’ mind holds some state that is visible to most classes, and can be used in Actions and Conditions.

Acknowldgements & Copyright Notices

dorcas/sample/audio/cuckoo_chime.wav

Is cut from Cuckoo Clock-Half hour.wav by lonemonk – https://freesound.org/s/88725/ License: Attribution 3.0

dorcas/sample/audio/announcement_chimes.wav

Tannoy chime 02.wav by kwahmah_02 https://freesound.org/s/245953/ License: Attribution 3.0

TODO

• MQTT re-connection
• Studio ceiling vibration sensor rules
• Greetings for people with bookings on tools, e.g. “your booking on the starts in 25 minutes.”