From 29ea2f46a81c516a08767eafdab9698d5cbd6150 Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Sat, 30 Jun 2018 12:22:35 +0200 Subject: Documentation cleanups. INSTALL -> INSTALL.md, README -> README.md --- README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..c6722aa --- /dev/null +++ b/README.md @@ -0,0 +1,124 @@ +Copyright (C) 2014-2018 - Simeon Simeonov +See the end of the file for license conditions. + + +## What is BEINC? + +Blackmore's Enchanced IRC Notification Collection (BEINC) is a free set of +components that aims to provide a complete system for different +on-screen-display notification scenarios. + +The current version of BEINC contains the following components: +beinc_server.py - server used for queueing or providing on-screen-display (OSD) +beinc_poller.py - client used to fetch enqueued messages from beinc_server.py + and provide OSD +beinc_weechat.py - a complete script / client for the Weechat IRC client >=0.4.0 + used to push notification messages to beinc_server.py +beinc_generic_client.py - a simple client used to push notification messages + to beinc_server.py + Its main purpose is to provide a convenient way to + test beinc_server.py (and beinc_poller.py) as well as + to serve as an example for how to develop BEINC-clients ++ documentation and a sample configuration file (beinc_config_sample.json) + + +## Why should I use BEINC and what has it done for me lately? + +BEINC is a free-software, licensed under the GPL3. It gives you the freedoms +of using it, studying it and modifying it. + +BEINC is designed to assist you two common scenarios. +As an example we will consider the case of an IRC cliet, although BEINC can be +used by any client that conforms with BEINC's "messaging protocol". + +We have the common situation where a user is accessing an IRC client located on +a different computer (typically: weechat, irssi, etc. running on a remote server) +The IRC client receives a private message (or any event that requires the user's +attention) and the user has to be notified. +No matter which of the two scenarios applies to your needs, you should start by + - setting up a BEINC client similar to beinc_generic_client.py on the server + If you are running weechat >=0.4.0, this version of BEINC comes with + a complete weechat BEINC-client: beinc_weechat.py + Configure the client to send notifications to the beinc_server.py +N.B. Using encryption is important in these days and age. + + +### Scenario one + +The user's computer can be reached by the server running the IRC client. +If the server (running the IRC client) is able to connect to +a specified TCP port on the user's computer, this is sufficient for BEINC to +directly notify the user. Solution: + - set up the beinc_server.py on the desktop workstation (the computer where the + notification-message should be displayed). Define an unprivileged port for + beinc_server.py to listen on and enable its OSD capabilities + (through pynotify) + + +### Scenario two + +The user's computer can NOT be reached by the server running the IRC client. +This scenario is typical for users that are working on computers that can not +be reached from outside. + +Solution: + - find a server that can be reached by the server running the IRC client. + - set up the beinc_server.py on it. No OSD capabilities are needed (no X11). + Define instance(s) for queueing. Define a queue size + (how many notifications to store) for each of them. + - set up beinc_poller.py on the desktop workstation (the computer where the + notification-message should be displayed). + beinc_poller.py should be able to access the server running beinc_server.py + Polling interval of 5 seconds should be enough for most users. + +Read beinc_config_sample.json.readme for details on how to setup +beinc_server.py and beinc_weechat.py! +Use "-h" command line parameter to display the available options for +beinc_poller.py and beinc_generic_client.py +Each configured beinc_server.py instance has an unique name. +There are 2 operations that can be done on an instance: + - push - a client is sending a notification to the BEINC server. + A push is available for all instances. + - pull - a poller (f.i. beinc_poller.py) is fetching data from the instance-queue. + A pull is available only for instances defined for queueing. + (read beinc_config_sample.json.readme for details!) +Example: +If you defined a beinc_server.py instance with SSL-support, +your URL will be: https://hostname:port + + +## Supported systems & requirements + +Any system running the software required for the selected components. +All components tested on: Gentoo GNU/Linux 2014,2015, + Ubuntu GNU/Linux 14.4,14.10, + FreeBSD 10.x + + +### Requirements +All components: Python >= 2.7.9 or Python >= 3.4.* + +beinc_server.py: pynotify >= 0.1 (optional) +beinc_weechat.py: Weechat >= 0.4.0 +beinc_poller.py: pynotify >= 0.1 +beinc_generic_client.py: No additional software required + +Read INSTALL in this very same folder for more details about installing the requirements! + + +### License + +This file is part of BEINC. + +BEINC 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. + +This program 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 this program. If not, see -- cgit v1.3