blob: 6d5b16d57c85bdd702c49d1418cfc82a683b247c [file] [log] [blame]
Sergei Trofimov4e6afe92015-10-09 09:30:04 +01001Instrumentation
2===============
3
4The ``Instrument`` API provide a consistent way of collecting measurements from
5a target. Measurements are collected via an instance of a class derived from
6:class:`Instrument`. An ``Instrument`` allows collection of measurement from one
7or more channels. An ``Instrument`` may support ``INSTANTANEOUS`` or
8``CONTINUOUS`` collection, or both.
9
10Example
11-------
12
13The following example shows how to use an instrument to read temperature from an
14Android target.
15
16.. code-block:: ipython
17
18 # import and instantiate the Target and the instrument
19 # (note: this assumes exactly one android target connected
20 # to the host machine).
21 In [1]: from devlib import AndroidTarget, HwmonInstrument
22
23 In [2]: t = AndroidTarget()
24
25 In [3]: i = HwmonInstrument(t)
26
27 # Set up the instrument on the Target. In case of HWMON, this is
28 # a no-op, but is included here for completeness.
29 In [4]: i.setup()
30
31 # Find out what the instrument is capable collecting from the
32 # target.
33 In [5]: i.list_channels()
34 Out[5]:
35 [CHAN(battery/temp1, battery_temperature),
36 CHAN(exynos-therm/temp1, exynos-therm_temperature)]
37
38 # Set up a new measurement session, and specify what is to be
39 # collected.
40 In [6]: i.reset(sites=['exynos-therm'])
41
42 # HWMON instrument supports INSTANTANEOUS collection, so invoking
43 # take_measurement() will return a list of measurements take from
44 # each of the channels configured during reset()
45 In [7]: i.take_measurement()
46 Out[7]: [exynos-therm_temperature: 36.0 degrees]
47
48API
49---
50
51Instrument
52~~~~~~~~~~
53
54.. class:: Instrument(target, **kwargs)
55
56 An ``Instrument`` allows collection of measurement from one or more
57 channels. An ``Instrument`` may support ``INSTANTANEOUS`` or ``CONTINUOUS``
58 collection, or both.
59
60.. attribute:: Instrument.mode
61
62 A bit mask that indicates collection modes that are supported by this
63 instrument. Possible values are:
64
65 :INSTANTANEOUS: The instrument supports taking a single sample via
66 ``take_measurement()``.
67 :CONTINUOUS: The instrument supports collecting measurements over a
68 period of time via ``start()``, ``stop()``, and
69 ``get_data()`` methods.
70
71 .. note:: It's possible for one instrument to support more than a single
72 mode.
73
74.. attribute:: Instrument.active_channels
75
76 Channels that have been activated via ``reset()``. Measurements will only be
77 collected for these channels.
78
79.. method:: Instrument.list_channels()
80
81 Returns a list of :class:`InstrumentChannel` instances that describe what
82 this instrument can measure on the current target. A channel is a combination
83 of a ``kind`` of measurement (power, temperature, etc) and a ``site`` that
84 indicates where on the target the measurement will be collected from.
85
86.. method:: Instrument.get_channels(measure)
87
88 Returns channels for a particular ``measure`` type. A ``measure`` can be
89 either a string (e.g. ``"power"``) or a :class:`MeasurmentType` instance.
90
91.. method:: Instrument.setup(*args, **kwargs)
92
93 This will set up the instrument on the target. Parameters this method takes
94 are particular to subclasses (see documentation for specific instruments
95 below). What actions are performed by this method are also
96 instrument-specific. Usually these will be things like installing
97 executables, starting services, deploying assets, etc. Typically, this method
98 needs to be invoked at most once per reboot of the target (unless
99 ``teardown()`` has been called), but see documentation for the instrument
100 you're interested in.
101
102.. method:: Instrument.reset([sites, [kinds]])
103
104 This is used to configure an instrument for collection. This must be invoked
105 before ``start()`` is called to begin collection. ``sites`` and ``kinds``
106 parameters may be used to specify which channels measurements should be
107 collected from (if omitted, then measurements will be collected for all
108 available sites/kinds). This methods sets the ``active_channels`` attribute
109 of the ``Instrument``.
110
111.. method:: Instrument.take_measurment()
112
113 Take a single measurement from ``active_channels``. Returns a list of
114 :class:`Measurement` objects (one for each active channel).
115
116 .. note:: This method is only implemented by :class:`Instrument`\ s that
117 support ``INSTANTANEOUS`` measurment.
118
119.. method:: Instrument.start()
120
121 Starts collecting measurements from ``active_channels``.
122
123 .. note:: This method is only implemented by :class:`Instrument`\ s that
124 support ``CONTINUOUS`` measurment.
125
126.. method:: Instrument.stop()
127
128 Stops collecting measurements from ``active_channels``. Must be called after
129 :func:`start()`.
130
131 .. note:: This method is only implemented by :class:`Instrument`\ s that
132 support ``CONTINUOUS`` measurment.
133
134.. method:: Instrument.get_data(outfile)
135
136 Write collected data into ``outfile``. Must be called after :func:`stop()`.
137 Data will be written in CSV format with a column for each channel and a row
138 for each sample. Column heading will be channel, labels in the form
139 ``<site>_<kind>`` (see :class:`InstrumentChannel`). The order of the coluns
140 will be the same as the order of channels in ``Instrument.active_channels``.
141
142 This returns a :class:`MeasurementCsv` instance associated with the outfile
143 that can be used to stream :class:`Measurement`\ s lists (similar to what is
144 returned by ``take_measurement()``.
145
146 .. note:: This method is only implemented by :class:`Instrument`\ s that
147 support ``CONTINUOUS`` measurment.
148
149
150Instrument Channel
151~~~~~~~~~~~~~~~~~~
152
153.. class:: InstrumentChannel(name, site, measurement_type, **attrs)
154
155 An :class:`InstrumentChannel` describes a single type of measurement that may
156 be collected by an :class:`Instrument`. A channel is primarily defined by a
157 ``site`` and a ``measurement_type``.
158
159 A ``site`` indicates where on the target a measurement is collected from
160 (e.g. a volage rail or location of a sensor).
161
162 A ``measurement_type`` is an instance of :class:`MeasurmentType` that
163 describes what sort of measurment this is (power, temperature, etc). Each
164 mesurement type has a standard unit it is reported in, regardless of an
165 instrument used to collect it.
166
167 A channel (i.e. site/measurement_type combination) is unique per instrument,
168 however there may be more than one channel associated with one site (e.g. for
169 both volatage and power).
170
171 It should not be assumed that any site/measurement_type combination is valid.
172 The list of available channels can queried with
173 :func:`Instrument.list_channels()`.
174
175.. attribute:: InstrumentChannel.site
176
177 The name of the "site" from which the measurments are collected (e.g. voltage
178 rail, sensor, etc).
179
180.. attribute:: InstrumentChannel.kind
181
182 A string indingcating the type of measrument that will be collted. This is
183 the ``name`` of the :class:`MeasurmentType` associated with this channel.
184
185.. attribute:: InstrumentChannel.units
186
187 Units in which measurment will be reported. this is determined by the
188 underlying :class:`MeasurmentType`.
189
190.. attribute:: InstrumentChannel.label
191
192 A label that can be attached to measurments associated with with channel.
193 This is constructed with ::
194
195 '{}_{}'.format(self.site, self.kind)
196
197
198Measurement Types
199~~~~~~~~~~~~~~~~~
200
201In order to make instruments easer to use, and to make it easier to swap them
202out when necessary (e.g. change method of collecting power), a number of
203standard measurement types are defined. This way, for example, power will always
204be reported as "power" in Watts, and never as "pwr" in milliWatts. Currently
205defined measurement types are
206
207
208+-------------+---------+---------------+
209| name | units | category |
210+=============+=========+===============+
211| time | seconds | |
212+-------------+---------+---------------+
213| temperature | degrees | |
214+-------------+---------+---------------+
215| power | watts | power/energy |
216+-------------+---------+---------------+
217| voltage | volts | power/energy |
218+-------------+---------+---------------+
219| current | amps | power/energy |
220+-------------+---------+---------------+
221| energy | joules | power/energy |
222+-------------+---------+---------------+
223| tx | bytes | data transfer |
224+-------------+---------+---------------+
225| rx | bytes | data transfer |
226+-------------+---------+---------------+
227| tx/rx | bytes | data transfer |
228+-------------+---------+---------------+
229
230
231.. instruments:
232
233Available Instruments
234---------------------
235
236This section lists instruments that are currently part of devlib.
237
238TODO