Table of content¶
Plugin documentation¶
Last change¶
New instructions to apply changes from immediatly previous version.
- 0.3.0 : (07-09-2016) First published version for domogik 0.5
- Version without xpl, work with 0MQ
- Update device_type, recreate domogik device with them.
- Previous change
Purpose¶
This Domogik plugin send notification message through services that could SMS (from web), Newtifry for Android.
Used with scenario could inform you of house event.
Offer a simply class developpement to add service.
Plugin configuration¶
Configuration¶
In Domogik administration section, go to client plugin-notify details page.
Key | Default value | Description |
---|---|---|
startup-plugin | false | Automatically start plugin at Domogik startup |
msg_header | Domogik notification | Define header of all messages. |
send_at_start | false | Send a notification message to all notify clients at starting plugin |
Creating devices for SMS Client¶
In clients page of admin UI, go to plugin-notify-<your_host_domogik>, select tab “Devices”, “New” to create your devices.
Chose one way creation by product or device type.
device_types : notify.smsweb¶
Key | Example | Description |
---|---|---|
Device | My phone id | The display name for this device. |
Description | What you want | A short description for this device. |
Reference | What you want | A reference for this device. |
Global to | My Phone number | Phone number to send SMS. |
Global operator | Freemobile service |
|
Global login | My user login | User login service. |
Global pwd | My password | User password service. |
Instance-type : notify.newtifry¶
Configure your Newtifry acces
Development informations¶
How it work ?¶
The plugin use clients who send message through operator service.
Operator could be any web service or hardware (in future stuff)
Clients service are register by plugin and communicat with they by internal code.
Header defined in plugin configuration is added at the top of message.
xPL messages¶
No xPL message handle, use only 0MQ
Existing clients service.¶
- Sending SMS WEB:
Send SMS using web service phone operator, actually there is 4 french operators handled : Can use just optional value
title
- Bouygues Telecom : file
bin/smsweb_bouygues.py
who use web service on http://www.mobile.service.bbox.bouyguestelecom.fr/services/SMSIHD/sendSMS.phtm
- Bouygues Telecom : file
- Free mobile : file
bin/smsweb_freemobile.py
who use web service on
- Free mobile : file
- Orange : file
bin/smsweb_orange.py
who use web service on
- Orange : file
- SFR : file
bin/smsweb_sfr.py
who use web service on
- SFR : file
- Sending Newtifry for Android:
Send notification using web service phone Newtifry API Can use all optional value
title
,priority
,url
,image
Developing new notification service¶
Plugin offer way to add new client service.
3 step are needed.
1 - Editin JSON file plugin¶
Some adding must be necessary to do in info.json file:
For an SMS web service just add your operator id in
parameters
,operator
, keychoices
ofdevice_types
, instancenotify.smsweb
:...... "notify.smsweb" : { "description" : "Send SMS using web service phone operator.", "id" : "notify.smsweb", "name" : "SMS operator web service", "commands" : ["send_msg"], "sensors" : ["msg_status", "error_send"], "parameters" : [{ "key" : "to", "xpl": false, "description" : "Phone number to send SMS.", "type" : "string" },{ "key" : "operator", "xpl": false, "description" : "Operator service.", "type" : "enum", "choices" : { "Bouygues_sms-web" : "Bouygues service", "Freemobile_sms-web" : "Freemobile service", "Orange_sms-web" : "Orange service", "SFR_sms-web" : "SFR service", # add coma "My_NEW_OPERATOR" : "NEW service" # add ligne } },{ "key" : "login", "xpl": false, "description" : "User login service.", "type" : "string" },{ "key" : "pwd", "xpl": false, "description" : "User password service.", "type" : "string" } ] }, .....
For a new service or hardware, create your own device_types
"notify.mynewservice" : { "description" : "A simple description of service.", "id" : "notify.mynewservice", "name" : "Name service", "commands" : ["send_extendmsg or send_msg"], # chose type of message "sensors" : ["msg_status", "error_send"], "parameters" : [{ "key" : "to", # keep this key, identification of recipient "xpl": false, # set to false for don't use in xPL message "description" : "A simple description of recipient.", "type" : "string" },{ "key" : "key1", # a optional key needed by service, like user/login/.... "xpl": false, # set to false for don't use in xPL message "description" : "A simple description of function.", "type" : "string" },{ "key" : "key2", # a optional key needed by service, like password/.... "xpl": false, # set to false for don't use in xPL message "description" : "A simple description of function.", "type" : "string" },{ ..... } ] } },
2 - Editing clients_devices.py file¶
File lib/clients_devices.py
contains a BaseClientService
python class who handle basic methodes.
You create a new class inherit this base class and overwriting some methodes to get acces of this new service or hardware.
There is 3 thinks to do in this file :
- 1st : Add your new operator id in OPERATORS_SERVICE global variable.
- This id is the same than JSON file
OPERATORS_SERVICE = ['SFR_sms-web', 'Orange_sms-web', 'Bouygues_sms-web', 'Freemobile_sms-web', 'Newtifry', My_NEW_OPERATOR]
2nd : You have to add new client device class reference in
CreateOperator
methode.def CreateOperator(params, log = None): """ Create a device depending of operator, use instance class to get parameters. - Developer : add your python class derived from DeviceBase class.""" .... elif params['operator'] == 'My_new_service' : from domogik_packages.plugin_notify.lib.mynewcodefile import MyNewClient newOperator = MyNewClient(params, log) ....
3rd : If you have ceated a new instance_type, you have to add new client getting specifique parameters in
GetDeviceParams
methode.def GetDeviceParams(Plugin, device): """ Return all internal parameters depending of instance_type. - Developer : add your instance_type proper parameters @param Plugin : Plugin base class reference for "get_parameter" methods access. type : object class Plugin @param device : domogik device data. type : dict @return : parameters for creating or update ClientService object. Value must contain at least keys : - 'operator' = Selected from OPERATORS_SERVICE - 'to' = Client reference, the same as global parameter 'to' type : dict """ ... elif device['device_type_id'] == 'newtifry.device': operator = 'My_NEW_OPERATOR' id = device['parameters']['to']['value'] # keep this line valueKey1 = device['parameters']['Key1']['value'] # Get your new device paramaters valuekey2 = device['parameters']['Key2']['value'] # Get your new device paramaters valuekey3 = Plugin.get_parameter(device, 'defaulttitle') # Get a Plugin config paramaters if needed if operator and device["name"] and id and valueKey1 and valuekey3: # check for none optional parameters # Build a dict with parameters params = {'name': device["name"] , 'operator' : operator, 'to' : id, 'key1' : valueKey1, 'key2' : valuekey2, 'key3' : valuekey3} return params # return your own parameters ...
Creating new client class¶
In a new python file place in lib :
- Import BaseClientService from plugin lib
from client_devices import BaseClientService
- Create your python class
class My_New_Client(BaseClientService): # simply new class declaration
def send(self, message): # overwrite methodes class
......
Overwrite update
methode¶
This method is called by plugin to update proper parameters, so set your own parameters in:
def update(self, params):
""" Create or update internal data, must be overwrited if others params needed.
@param params : parameters from GetDeviceParams() of domogik device'.
type : dict
"""
BaseClientService.update(self, params) # keep this line to call basic method
self.key1 = params['key1'] # your parameter
self.key2 = params['key2'] if 'key2' in params else None # your parameter
Overwrite send
methode¶
This method is called by plugin for sending message on service, She must return a dict with format : use self._log to log message in plugin log.
{
'status' : <A simple text to say sended or not>,
'error' : <Error cause or empty ('') if no error>
}
def send(self, message):
""" Send message
@param message : message dict data contain at least keys:
- 'to' : recipient of the message
- 'header' : header for message set in plugin configuration
- 'body" : message
- extra key defined in 'command' json declaration like 'title', priority', ....
@return : dict = {'status' : <Status info>, 'error' : <Error Message>}
"""
...
# write your own code for format message and send it.
# using try / except should avoid failling plugin
try :
...
except :
result = {'status': u"Message not sended", 'error': u"Bad message format : {0}".format(message)}
self._log.warning(u"{0} Message <{1}> not sended. {2}".format(self.to, message, traceback.format_exc())) # use traceback in lo
...
if message_Is_Sended : return {'status': 'Message sended :)', 'error': ''}
else return {'status': 'Message not sended :(', 'error': 'Server not response .....'}
0.3.2¶
- Freemobile sms service : - Fix UrlLib2 ssl CERTIFICATE_VERIFY_FAILED error 590, due to python lib update (2018 june) - Improve Error connection service.
- Fix #9 Add send at stop configuration option
- Fix #8 Unicode for device name (log)
0.3.1¶
- Fix Unicode for device name
0.3.0¶
- domogik 0.5 upgrade
- Version without xpl, work with 0MQ
- Update device_type, recreate domogik device with them.
- Add disconnect notification
- Live domogik device create/update, no need to restrat plugin
- Update user and develop doc.
0.2a0¶
- Fusion of sms and apushnot plugin
- domogik 0.4 upgrade, add freemobile operator and Newtifry for android.
0.1.2¶
- Initial version from domogik 0.3 plugin