diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 122 |
1 files changed, 0 insertions, 122 deletions
| @@ -1,122 +0,0 @@ | |||
| 1 | Copyright (C) 2014-2018 - Simeon Simeonov | ||
| 2 | See the end of the file for license conditions. | ||
| 3 | |||
| 4 | |||
| 5 | What is BEINC? | ||
| 6 | -------------- | ||
| 7 | |||
| 8 | Blackmore's Enchanced IRC Notification Collection (BEINC) is a free set of | ||
| 9 | components that aims to provide a complete system for different | ||
| 10 | on-screen-display notification scenarios. | ||
| 11 | |||
| 12 | The current version of BEINC contains the following components: | ||
| 13 | beinc_server.py - server used for queueing or providing on-screen-display (OSD) | ||
| 14 | beinc_poller.py - client used to fetch enqueued messages from beinc_server.py | ||
| 15 | and provide OSD | ||
| 16 | beinc_weechat.py - a complete script / client for the Weechat IRC client >=0.4.0 | ||
| 17 | used to push notification messages to beinc_server.py | ||
| 18 | beinc_generic_client.py - a simple client used to push notification messages | ||
| 19 | to beinc_server.py | ||
| 20 | Its main purpose is to provide a convenient way to | ||
| 21 | test beinc_server.py (and beinc_poller.py) as well as | ||
| 22 | to serve as an example for how to develop BEINC-clients | ||
| 23 | + documentation and a sample configuration file (beinc_config_sample.json) | ||
| 24 | |||
| 25 | |||
| 26 | Why should I use BEINC and what has it done for me lately? | ||
| 27 | ---------------------------------------------------------- | ||
| 28 | |||
| 29 | BEINC is a free-software, licensed under the GPL3. It gives you the freedoms | ||
| 30 | of using it, studying it and modifying it. | ||
| 31 | |||
| 32 | BEINC is designed to assist you two common scenarios. | ||
| 33 | As an example we will consider the case of an IRC cliet, although BEINC can be | ||
| 34 | used by any client that conforms with BEINC's "messaging protocol". | ||
| 35 | |||
| 36 | We have the common situation where a user is accessing an IRC client located on | ||
| 37 | a different computer (typically: weechat, irssi, etc. running on a remote server) | ||
| 38 | The IRC client receives a private message (or any event that requires the user's | ||
| 39 | attention) and the user has to be notified. | ||
| 40 | No matter which of the two scenarios applies to your needs, you should start by | ||
| 41 | - setting up a BEINC client similar to beinc_generic_client.py on the server | ||
| 42 | If you are running weechat >=0.4.0, this version of BEINC comes with | ||
| 43 | a complete weechat BEINC-client: beinc_weechat.py | ||
| 44 | Configure the client to send notifications to the beinc_server.py | ||
| 45 | N.B. Using encryption is important in these days and age. | ||
| 46 | |||
| 47 | Scenario one: | ||
| 48 | The user's computer can be reached by the server running the IRC client. | ||
| 49 | If the server (running the IRC client) is able to connect to | ||
| 50 | a specified TCP port on the user's computer, this is sufficient for BEINC to | ||
| 51 | directly notify the user. Solution: | ||
| 52 | - set up the beinc_server.py on the desktop workstation (the computer where the | ||
| 53 | notification-message should be displayed). Define an unprivileged port for | ||
| 54 | beinc_server.py to listen on and enable its OSD capabilities | ||
| 55 | (through pynotify) | ||
| 56 | |||
| 57 | Scenario two: | ||
| 58 | The user's computer can NOT be reached by the server running the IRC client. | ||
| 59 | This scenario is typical for users that are working on computers that can not | ||
| 60 | be reached from outside. | ||
| 61 | Solution: | ||
| 62 | - find a server that can be reached by the server running the IRC client. | ||
| 63 | - set up the beinc_server.py on it. No OSD capabilities are needed (no X11). | ||
| 64 | Define instance(s) for queueing. Define a queue size | ||
| 65 | (how many notifications to store) for each of them. | ||
| 66 | - set up beinc_poller.py on the desktop workstation (the computer where the | ||
| 67 | notification-message should be displayed). | ||
| 68 | beinc_poller.py should be able to access the server running beinc_server.py | ||
| 69 | Polling interval of 5 seconds should be enough for most users. | ||
| 70 | |||
| 71 | Read beinc_config_sample.json.readme for details on how to setup | ||
| 72 | beinc_server.py and beinc_weechat.py! | ||
| 73 | Use "-h" command line parameter to display the available options for | ||
| 74 | beinc_poller.py and beinc_generic_client.py | ||
| 75 | Each configured beinc_server.py instance has an unique name. | ||
| 76 | There are 2 operations that can be done on an instance: | ||
| 77 | - push - a client is sending a notification to the BEINC server. | ||
| 78 | A push is available for all instances. | ||
| 79 | - pull - a poller (f.i. beinc_poller.py) is fetching data from the instance-queue. | ||
| 80 | A pull is available only for instances defined for queueing. | ||
| 81 | (read beinc_config_sample.json.readme for details!) | ||
| 82 | Example: | ||
| 83 | If you defined a beinc_server.py instance with SSL-support, | ||
| 84 | your URL will be: https://hostname:port | ||
| 85 | |||
| 86 | |||
| 87 | Supported systems & requirements | ||
| 88 | -------------------------------- | ||
| 89 | Any system running the software required for the selected components. | ||
| 90 | All components tested on: Gentoo GNU/Linux 2014,2015, | ||
| 91 | Ubuntu GNU/Linux 14.4,14.10, | ||
| 92 | FreeBSD 10.x | ||
| 93 | |||
| 94 | |||
| 95 | Requirements: | ||
| 96 | All components: Python >= 2.7.9 or Python >= 3.4.* | ||
| 97 | |||
| 98 | beinc_server.py: pynotify >= 0.1 (optional) | ||
| 99 | beinc_weechat.py: Weechat >= 0.4.0 | ||
| 100 | beinc_poller.py: pynotify >= 0.1 | ||
| 101 | beinc_generic_client.py: No additional software required | ||
| 102 | |||
| 103 | Read INSTALL in this very same folder for more details about installing the requirements! | ||
| 104 | |||
| 105 | |||
| 106 | License | ||
| 107 | ------- | ||
| 108 | |||
| 109 | This file is part of BEINC. | ||
| 110 | |||
| 111 | BEINC is free software: you can redistribute it and/or modify | ||
| 112 | it under the terms of the GNU General Public License as published by | ||
| 113 | the Free Software Foundation, either version 3 of the License, or | ||
| 114 | (at your option) any later version. | ||
| 115 | |||
| 116 | This program is distributed in the hope that it will be useful, | ||
| 117 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 118 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 119 | GNU General Public License for more details. | ||
| 120 | |||
| 121 | You should have received a copy of the GNU General Public License | ||
| 122 | along with this program. If not, see <http://www.gnu.org/licenses/> | ||
