joedougherty / distractinator Goto Github PK

View Code? Open in Web Editor NEW

0.0 3.0 2.0 33 KB

The customizable, open source cubicle doorbell

License: MIT License

Python 89.50% C++ 10.50%

arduino hardware-interactions python-script

distractinator's Introduction

DISTRACTINATOR: The customizable, open source cubicle doorbell

Installation

pip install distractinator

Note: You may need to sudo pip install as this will attempt to write to /usr/local/bin/

SETUP

distractd

You will be walked through a few steps to ensure the script can communicate with your receiver. The setup process will also copy an example config file to your home directory, at ~/.distractinator.conf.

If You Encounter a Permissions Issue During setup

The default permissions on the device may not allow for reading and writing. If the setup process asks you to check the permissions on the device, try the following:

$ sudo usermod -aG dialout $USER
$ newgrp dialout

After these commands have been run, call distractd once again.

Specifying a logfile:

By default, the log messages will print to stdout. You can specify a logfile location with the --log argument.

distractd --log /path/to/distractd.log

This is especially helpful when running as a background process, or under the supervision of a separate process.

HOW TO RUN

distractd works best when it runs any time your machine is on. Here are a few strategies for running it without too much hassle on Ubuntu.

Use a systemd unit file

Any systemd unit file placed in ~/.config/systemd/user/ can be managed with normal user privileges. For example:

$ cat ~/.config/systemd/user/distractd.service
[Unit]
Description=Distractinator Service Daemon

[Service]
ExecStart=/usr/bin/python %h/.local/bin/distractd

[Install]
WantedBy=default.target

Enable the service:

systemctl --user enable distractd.service

Then to start:

systemctl --user start distractd.service

The above path to the distractd script in the ExecStart line assumes the package was installed with the --user flag. Update accordingly if you installed distractinator system-wide.

Add an entry to Startup Applications

/usr/local/bin/distractd --log /path/to/distractd.log

Run it under Supervisord

pip install supervisor

Example stanza for supervisord.conf:

[program:distractd]
command=/usr/local/bin/distractd
autostart=True
autorestart=unexpected
user=joe ; Replace with your user
exitcodes=0,2
redirect_stderr=True
stdout_logfile=/path/to/distractd.log

CUSTOM EVENTS

customevents.py

You should use one!

This repository comes with an example customevents.py file. Find its path on your system with:

distractd --example_custom_code

Copy that file to your desired location
Uncomment the custom_script variable in your config file
Point it to the absolute path of your customevents.py file

You will need to restart distractd to pick up changes to customevents.py.

distractinator's People

Contributors

Watchers

Forkers

conorsch metllord

distractinator's Issues

Publish to PyPI

It'd be grand to be able to install distractinator via pip without having to clone done this git repo. Just a thought!

Log/Handle serial.serialutil.SerialException(s)

My distractd process died recently, but this output was only available via console.

This should at least be logged. It really ought to throw some kind of non-silent error (perhaps as a notification itself)?

1.) Figure out how to reproduce error.
2.) Log.
3.) Find appropriate notification mechanism to let user know the process died.

Example traceback:

Traceback (most recent call last):
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/serial/serialposix.py", line 501, in read
    'device reports readiness to read but returned no data '
serial.serialutil.SerialException: device reports readiness to read but returned no data (device disconnected or multiple access on port?)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/distractinator/Distractinator.py", line 220, in run
    serialMsg = port.readline().strip()
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/serial/serialposix.py", line 509, in read
    raise SerialException('read failed: {}'.format(e))
serial.serialutil.SerialException: read failed: device reports readiness to read but returned no data (device disconnected or multiple access on port?)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/serial/serialposix.py", line 501, in read
    'device reports readiness to read but returned no data '
serial.serialutil.SerialException: device reports readiness to read but returned no data (device disconnected or multiple access on port?)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/josepd/VENV/d2/bin/distractd", line 11, in <module>
    sys.exit(main())
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/distractinator/__init__.py", line 5, in main
    d.run()
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/distractinator/Distractinator.py", line 228, in run
    serialMsg = port.readline().strip()
  File "/home/josepd/VENV/d2/lib/python3.6/site-packages/serial/serialposix.py", line 509, in read
    raise SerialException('read failed: {}'.format(e))
serial.serialutil.SerialException: read failed: device reports readiness to read but returned no data (device disconnected or multiple access on port?)

Document config file location in README

While setting up distractinator and trying to set up custom events, it took me a few tries to nail down where the config file is located: ~/.distractinator.conf. Admittedly the distractd setup process does print the location to STDOUT during configuration, but I missed it because I'm irresponsible and shouldn't be allowed near computers.

Simply placing a reference to it in the README may alleviate confusion for others.

Permission denied exception on first run

While running distractd for the first time, the script correctly identified the USB device:

Press enter to continue!
[0]: 
        Device: /dev/ttyACM0
        Manufacturer: Flora
        Hardware ID: USB VID:PID=239A:8004 LOCATION=2-2

But selecting it via 0 to continue raised a serial.serialutil.SerialException:

Select a port ('retry' if you still need to plug in the Distractinator(TM)): 0
[2016-12-03 16:10:18,111] INFO     custom_script variable not set in config file.
[2016-12-03 16:10:18,111] INFO     Attempting to find + connect to USB device...
[2016-12-03 16:10:18,117] INFO     Found device at address: /dev/ttyACM0
Traceback (most recent call last):
  File "/home/conor/.virtualenvs/distractinator/bin/distractd", line 9, in <module>
    load_entry_point('distractinator==0.2', 'console_scripts', 'distractd')()
  File "/home/conor/.virtualenvs/distractinator/local/lib/python2.7/site-packages/distractinator/__init__.py", line 4, in main
    d = Distractinator()
  File "/home/conor/.virtualenvs/distractinator/local/lib/python2.7/site-packages/distractinator/Distractinator.py", line 56, in __init__
    self.p = self.autoconnect() # Won't you join me on the perennial quest?
  File "/home/conor/.virtualenvs/distractinator/local/lib/python2.7/site-packages/distractinator/Distractinator.py", line 164, in autoconnect
    return serial.Serial(p.device, 9600, timeout=10)
  File "/home/conor/.virtualenvs/distractinator/local/lib/python2.7/site-packages/serial/serialutil.py", line 236, in __init__
    self.open()
  File "/home/conor/.virtualenvs/distractinator/local/lib/python2.7/site-packages/serial/serialposix.py", line 268, in open
    raise SerialException(msg.errno, "could not open port {}: {}".format(self._port, msg))
serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyACM0: [Errno 13] Permission denied: '/dev/ttyACM0'

This was caused by default device permissions on Ubuntu 16.04 requiring special group membership:

$ ls -l /dev/ttyACM0
crw-rw---- 1 root dialout 166, 0 Dec  3 15:42 /dev/ttyACM0

Resolved it with:

$ sudo usermod -aG dialout $USER
$ newgrp dialout

Then reran the script and everything was hunky-dory. Would suggest two changes to help first-time users:

Catch the serial.serialutil.SerialException and display an informative error message.
Document the group membership tidbit in the README. (The target group may vary by platform, haven't tested widely.)

Show example systemd unit file

Right now the README includes helpful examples for two methods of running distractd as a service:

adding to autostart programs
using with supervisord

Most Linux distros have moved to systemd by now, and a seldom-used feature of systemd is that it provides a simple way to configure services management with normal user privileges, as long as the unit files are placed in ~/.config/systemd/user/. For example, I'm now doing this:

$ cat ~/.config/systemd/user/distractd.service 
[Unit]
Description=Distractinator Service Daemon

[Service]
ExecStart=/usr/bin/python %h/.local/bin/distractd

[Install]
WantedBy=default.target

Then a simple systemctl --user start distractd and it's humming along nicely.