pylibcerebrum/ganglion.py

   1 #!/usr/bin/env python3
   2 #
   3 #Copyright (C) 2012 jaseg <s@jaseg.de>
   4 #
   5 #This program is free software; you can redistribute it and/or
   6 #modify it under the terms of the GNU General Public License
   7 #version 3 as published by the Free Software Foundation.
   8
   9 import json
  10 import struct
  11 try:
  12         import lzma
  13 except:
  14         import pylzma as lzma
  15 import time
  16 import serial
  17 from pylibcerebrum.NotifyList import NotifyList
  18 from pylibcerebrum.timeout_exception import TimeoutException
  19
  20 escape = lambda s: s.replace(b'\\', b'\\\\')
  21
  22 """Call RPC functions on serially connected devices over the Cerebrum protocol."""
  23
  24 class Ganglion(object):
  25         """Proxy class for calling remote methods on hardware connected through a serial port using the Cerebrum protocol"""
  26
  27         # NOTE: the device config is *not* the stuff from the config "dev" section but
  28         #read from the device. It can also be found in that [devicename].config.json
  29         #file created by the code generator
  30         def __init__(self, node_id, jsonconfig=None, ser=None, name=''):
  31                 """Ganglion constructor
  32
  33                 Keyword arguments:
  34                 device -- the device file to connect to
  35                 baudrate -- the baudrate to use (default 115200)
  36                 The other keyword arguments are for internal use only.
  37
  38                 """
  39                 object.__setattr__(self, '_ser', ser)
  40                 object.__setattr__(self, 'node_id', node_id)
  41                 object.__setattr__(self, 'name', name)
  42                 if not jsonconfig:
  43                         # get a config
  44                         i=0
  45                         while True:
  46                                 try:
  47                                         jsonconfig = self._read_config()
  48                                         time.sleep(0.1)
  49                                         break
  50                                 except TimeoutException as e:
  51                                         print('Timeout', e)
  52                                 except ValueError as e:
  53                                         print('That device threw some nasty ValueError\'ing JSON!', e)
  54                                 i += 1
  55                                 if i > 20:
  56                                         raise serial.serialutil.SerialException('Could not connect, giving up after 20 tries')
  57                 # populate the object
  58                 object.__setattr__(self, 'members', {})
  59                 for name, member in jsonconfig.get('members', {}).items():
  60                         self.members[name] = Ganglion(node_id, jsonconfig=member, ser=self._ser, name=self.name+'/'+name)
  61                 object.__setattr__(self, 'properties', {})
  62                 for name, prop in jsonconfig.get('properties', {}).items():
  63                         self.properties[name] = (prop['id'], prop['fmt'], prop.get('access', 'rw'))
  64                 object.__setattr__(self, 'functions', {})
  65                 for name, func in jsonconfig.get('functions', {}).items():
  66                         def proxy_method(*args):
  67                                 return self._callfunc(func["id"], func.get("args", ""), args, func.get("returns", ""))
  68                         self.functions[name] = proxy_method
  69                 object.__setattr__(self, 'type', jsonconfig.get('type', None))
  70                 object.__setattr__(self, 'config', { k: v for k,v in jsonconfig.items() if not k in ['members', 'properties', 'functions'] })
  71
  72         def __iter__(self):
  73                 """Construct an iterator to iterate over *all* (direct or not) child nodes of this node."""
  74                 return GanglionIter(self)
  75
  76         def _read_config(self):
  77                 """Fetch the device configuration descriptor from the device."""
  78                 with self._ser as s:
  79                         s.write(b'\\#' + escape(struct.pack(">H", self.node_id)) + b'\x00\x00\x00\x00')
  80                         (clen,) = struct.unpack(">H", s.read(2))
  81                         cbytes = s.read(clen)
  82                         #decide whether cbytes contains lzma or json depending on the first byte (which is used as a magic here)
  83                         if cbytes[0] is ord('#'):
  84                                 return json.JSONDecoder().decode(str(lzma.decompress(cbytes[1:]), "utf-8"))
  85                         else:
  86                                 return json.JSONDecoder().decode(str(cbytes, "utf-8"))
  87
  88         def _callfunc(self, fid, argsfmt, args, retfmt):
  89                 """Call a function on the device by id, directly passing argument/return format parameters."""
  90                 # Make a list out of the arguments if they are none
  91                 #print('calling function No. {}, args({}) {}, returning {}'.format(fid, argsfmt, args, retfmt))
  92                 if not (isinstance(args, tuple) or isinstance(args, list)):
  93                         args = [args]
  94                 with self._ser as s:
  95                         # Send the encoded data
  96                         cmd = b'\\#' + escape(struct.pack(">HHH", self.node_id, fid, struct.calcsize(argsfmt)) + struct.pack(argsfmt, *args))
  97                         s.write(cmd)
  98                         # payload length
  99                         (clen,) = struct.unpack(">H", s.read(2))
 100                         # payload data
 101                         cbytes = s.read(clen)
 102                         if clen != struct.calcsize(retfmt):
 103                                 # CAUTION! This error is thrown not because the user supplied a wrong value but because the device answered in an unexpected manner.
 104                                 # FIXME raise an error here or let the whole operation just fail in the following struct.unpack?
 105                                 raise AttributeError("Device response format problem: Length mismatch: {} != {}".format(clen, struct.calcsize(retfmt)))
 106                         rv = struct.unpack(retfmt, cbytes)
 107                         # Try to interpret the return value in a useful manner
 108                         if len(rv) == 0:
 109                                 return None
 110                         elif len(rv) == 1:
 111                                 return rv[0]
 112                         else:
 113                                 return list(rv)
 114
 115         def __dir__(self):
 116                 """Get a list of all attributes of this object. This includes virtual Cerebrum stuff like members, properties and functions."""
 117                 return list(self.members.keys()) + list(self.properties.keys()) + list(self.functions.keys()) + list(self.__dict__.keys())
 118
 119         # Only now add the setattr magic method so it does not interfere with the above code
 120         def __setattr__(self, name, value):
 121                 """Magic method to set an attribute. This one even handles remote Cerebrum properties."""
 122                 #check if the name is a known property
 123                 if name in self.properties:
 124                         #call the property's Cerebrum setter function
 125                         varid, varfmt, access = self.properties[name]
 126                         if not "w" in access:
 127                                 raise TypeError("{} is a read-only property".format(name))
 128                         return self._callfunc(varid+1, varfmt, value, "")
 129                 #if the above code falls through, do a normal __dict__ lookup.
 130                 self.__dict__[name] = value
 131
 132
 133         def __getattr__(self, name):
 134                 """Magic method to get an attribute of this object, considering Cerebrum members, properties and functions.
 135
 136                 At this point a hierarchy is imposed upon the members/properties/functions that is not present in the implementation:
 137
 138                 Between a member, a property and a function of the same name the member will be preferred over the property and the property will be preferred over the function. If you should manage to make device have such colliding names, consider using _callfunc(...) directly.
 139
 140                 """
 141                 if name in self.members:
 142                         return self.members[name]
 143
 144                 if name in self.properties:
 145                         def cb(newx):
 146                                 self.__setattr__(name, newx)
 147                         varid, varfmt, access = self.properties[name]
 148                         rv = self._callfunc(varid, "", (), varfmt)
 149                         # If the return value is a list, construct an auto-updating thingy from it.
 150                         if isinstance(rv, list):
 151                                 return NotifyList(rv, callbacks=[cb])
 152                         else:
 153                                 return rv
 154
 155                 if name in self.functions:
 156                         return self.functions[name]
 157
 158                 #If all of the above falls through...
 159                 raise AttributeError(name)
 160
 161 class GanglionIter:
 162         """Iterator class for ganglions that recursively iterates over all (direct or indirect) child nodes of a given Ganglion"""
 163
 164         def __init__(self, g):
 165                 self.g = g
 166                 self.keyiter = g.members.__iter__()
 167                 self.miter = None
 168
 169         def __iter__(self):
 170                 return self
 171
 172         def __next__(self):
 173                 try:
 174                         return self.miter.__next__()
 175                 except StopIteration:
 176                         pass
 177                 except AttributeError:
 178                         pass
 179                 foo = self.g.__getattr__(self.keyiter.__next__())
 180                 self.miter = foo.__iter__()
 181                 return foo
 182