As of August 2020 the site you are on (wiki.newae.com) is deprecated, and content is now at rtfm.newae.com.

Difference between revisions of "Adding Modules/Parameters"

From ChipWhisperer Wiki
Jump to: navigation, search
(Adding New Modules)
Line 17: Line 17:
 
The CW tools scan these directories looking for classes that inherits from the ''Plugin'' class in each public file (that don't beggins with "_").
 
The CW tools scan these directories looking for classes that inherits from the ''Plugin'' class in each public file (that don't beggins with "_").
  
These folders usually have a file called base.py or _base.py that contains the base class to all modules in these directories. Ex.:
+
These folders usually have a file called ''base.py'' or ''_base.py'' that contains the base class to all modules in these directories. Ex.:
  
 
<pre>
 
<pre>
Line 31: Line 31:
 
</pre>
 
</pre>
  
=Adding parameters=
+
=Adding Parameters=
  
Another important thing, is the Parameter architecture. It is used to allow easy access and manipulation of all object's main attibutes and actions. All parameters can be accessed statically throught the Parameter class. It means that if you want to set/get any parameter, you can do it easily adding the follow lines to your code:
+
Parameters are used to allow easy access and manipulation of all object's main attibutes and actions. All parameters can be accessed anywhere in the code throught the Parameter class. It means that if you want to set/get any parameter, you can do it easily adding the follow lines to your code:
 
<pre>
 
<pre>
 
from chipwhisperer.common.utils.parameter import Parameter
 
from chipwhisperer.common.utils.parameter import Parameter
Line 48: Line 48:
 
</pre>
 
</pre>
  
The easiest way to add parameters to your class, is to make it Parameterized (extending this class). It is an abstract class that declares a public interface and implements two manipulation methods to create/get the Parameters and find it. As a general rule, you just need to:
+
The easiest way to add parameters to your class, is to make it ''Parameterized'' (extending this class). It is an abstract class that declares a public interface and implements two manipulation methods to create/get the parameters and find it. As a general rule, you just need to:
* import the Parameterized class: from chipwhisperer.common.utils.parameter import Parameterized
+
 
* make your class extend it
+
* import the ''Parameterized'' class: from chipwhisperer.common.utils.parameter import Parameterized
 +
* make your class extend it (no construtor call is needed here since the idea is to use it as an interface to avoid the problems with multiple inheritance - i.e.: the diamont one)
 
* define a _name and a _description
 
* define a _name and a _description
 
* register it if it is not readily accessible through a higher parameter hierarchy: self.getParams().register()  
 
* register it if it is not readily accessible through a higher parameter hierarchy: self.getParams().register()  
* and call self.getParams().addChildren([...])
+
* call self.getParams().addChildren([...])
  
The method getParams() whild do four things: create a new Parameter if it doesn't exist; create a group called _name; create a child description parameter with the specified _description; and return a reference to the group parameter. Search in the parameters can be performed using the findParam([fullpath]) method.
+
The getParams() method does three things: create a new Parameter if it doesn't exist; create a group called _name; create a child description parameter with the specified _description label; and return a reference to the parent group parameter. Search is performed using the findParam([fullpath]) method.
 
Each parameter stores the data internally or externally using a set/get (usefull to retrieve dynamic data). In this case, the @setupSetParam(nameOrPath) decorator should be used in the set method in order to syncronize the GUI when the parameter value changes.
 
Each parameter stores the data internally or externally using a set/get (usefull to retrieve dynamic data). In this case, the @setupSetParam(nameOrPath) decorator should be used in the set method in order to syncronize the GUI when the parameter value changes.
  
Line 76: Line 77:
 
             {'name':'Symbol', 'type':'list', 'values':['o', 's', 't', 'd', '+'], 'value':'o'},                    # With value saved internally
 
             {'name':'Symbol', 'type':'list', 'values':['o', 's', 't', 'd', '+'], 'value':'o'},                    # With value saved internally
 
         ])
 
         ])
 +
 +
        self.findParam("Symbol").setValue('t')
 +
        s = self.findParam("Symbol").getValue()  # s = 't'
  
 
     def getEnabled(self):
 
     def getEnabled(self):

Revision as of 13:22, 17 June 2016

Adding New Modules

In the new CW software architecture, all plugin modules are scanned during the tool inialization, so new modules can added by just dropping the files inside its respective folder:

  • chipwhisperer/software/chipwhisperer/common/results
  • chipwhisperer/software/chipwhisperer/common/traces
  • chipwhisperer/software/chipwhisperer/capture/acq_patterns
  • chipwhisperer/software/chipwhisperer/capture/auxiliary
  • chipwhisperer/software/chipwhisperer/capture/scopes
  • chipwhisperer/software/chipwhisperer/capture/scripts
  • chipwhisperer/software/chipwhisperer/capture/targets
  • chipwhisperer/software/chipwhisperer/analyzer/attacks
  • chipwhisperer/software/chipwhisperer/analyzer/preprocessing
  • chipwhisperer/software/chipwhisperer/analyzer/scripts
  • and some of its subfolders.

The CW tools scan these directories looking for classes that inherits from the Plugin class in each public file (that don't beggins with "_").

These folders usually have a file called base.py or _base.py that contains the base class to all modules in these directories. Ex.:

from .base import PreprocessingBase
from chipwhisperer.common.utils.pluginmanager import Plugin


class AddNoiseRandom(PreprocessingBase, Plugin):
    _name = "Add Noise: Amplitude"
    _description = "Add random noise"
     
...

Adding Parameters

Parameters are used to allow easy access and manipulation of all object's main attibutes and actions. All parameters can be accessed anywhere in the code throught the Parameter class. It means that if you want to set/get any parameter, you can do it easily adding the follow lines to your code:

from chipwhisperer.common.utils.parameter import Parameter
...
Parameter.setParameter([path,..., value])
value = Parameter.getParameter([path,...])

or, if you have access to the api:

api.setParameter([path,..., value])
value = api.getParameter([path,...])

The easiest way to add parameters to your class, is to make it Parameterized (extending this class). It is an abstract class that declares a public interface and implements two manipulation methods to create/get the parameters and find it. As a general rule, you just need to:

  • import the Parameterized class: from chipwhisperer.common.utils.parameter import Parameterized
  • make your class extend it (no construtor call is needed here since the idea is to use it as an interface to avoid the problems with multiple inheritance - i.e.: the diamont one)
  • define a _name and a _description
  • register it if it is not readily accessible through a higher parameter hierarchy: self.getParams().register()
  • call self.getParams().addChildren([...])

The getParams() method does three things: create a new Parameter if it doesn't exist; create a group called _name; create a child description parameter with the specified _description label; and return a reference to the parent group parameter. Search is performed using the findParam([fullpath]) method. Each parameter stores the data internally or externally using a set/get (usefull to retrieve dynamic data). In this case, the @setupSetParam(nameOrPath) decorator should be used in the set method in order to syncronize the GUI when the parameter value changes.

More information about the Parameterized and the Parameter class can be found in its docstrings.

Basic exemple:

from chipwhisperer.common.utils.parameter import Parameterized, setupSetParam


class ResultsSave(Parameterized):
    _name = "Save to Files"
    _description = "Save correlation output to files."

    def __init__(self):
        # self.getParams().register()
        self.getParams().addChildren([
            {'name':'Save Raw Results', 'type':'bool', 'get':self.getEnabled, 'set':self.setEnabled},  # With value saved externally
            {'name':'Symbol', 'type':'list', 'values':['o', 's', 't', 'd', '+'], 'value':'o'},                     # With value saved internally
        ])

        self.findParam("Symbol").setValue('t')
        s = self.findParam("Symbol").getValue()  # s = 't'

    def getEnabled(self):
        return self._enabled

    @setupSetParam("Save Raw Results")
    def setEnabled(self, enabled):
        self._enabled = enabled