Skip to content

Ring Module

This module help you to manage the pybox rgb led ring.

Examples:

>>> from pybox.ring import RING
>>> from pybox.color import *
>>> ring = RING()
>>> ring.write(1)   # turn on whole ring (in RED)
>>> ring.write(0)   # turn off it

The user basically creates an instance of RING class. This object will creates a list of PIXEL objects, where a pixel si a representation of a rgb led in the ring.

Examples:

>>> # turn on/off the first pixel of the ring only
>>> ring[0].on()
>>> ring[0].off()

Classes

PIXEL

Pixel class.

A PIXEL object is an abstraction to manage a single rgb led, part of a RING object.

Parameters:

  • index (int, default: None ) –

    index of the pixel in the ring class list. Defaults to None.

  • color (tuple[int], default: RED ) –

    color of the Pixel. Defaults to RED.

  • ring (ARING, default: None ) –

    Ring reference. Defaults to None.

You don't create a PIXEL instance directly, but when you create a RING object, it creates a list of PIXEL objects.

Examples:

>>> ring = RING()
>>> type(ring[0])
<class 'PIXEL'>
Source code in pybox/ring.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class PIXEL:
    """Pixel class.

        A PIXEL object is an abstraction to manage a single rgb led, part of a RING object. 

        Args:
            index (int): index of the pixel in the ring class list. Defaults to None.
            color (tuple[int], optional): color of the Pixel. Defaults to RED.
            ring (ARING, optional): Ring reference. Defaults to None.

        You don't create a PIXEL instance directly, but when you create a RING object, it creates a list of PIXEL objects.

        Examples:
            >>> ring = RING()
            >>> type(ring[0])
            <class 'PIXEL'>
    """

    def __init__(self, index: int = None, color: tuple[int] = RED, ring: ARING = None):
        self.index = index
        self.__ring = ring
        self.__ring.set_pixel_color(index, color)

    def __repr__(self) -> str:
        return f"PIXEL object with index {self.index} and color {self.__ring.get_pixel_color(self.index)}"

    def on(self):
        """Turn on a pixel.

        Examples:
            >>> ring[0].on()   # turn on the pixel at index 0 with current color
        """
        self.__ring.set_pixel(self.index, 1)

    def off(self):
        """Turn off a pixel.

        Examples:
            >>> ring[0].off()   # turn off the pixel at index 0 with current color
        """
        self.__ring.set_pixel(self.index, 0)

    def toggle(self):
        """Turn on a pixel if the pixel is currently turned off and viceversa.
        """
        if self.__ring.is_on(self.index):
            self.off()
        else:
            self.on()

    def write(self, col: tuple = None) -> None:
        """Write a value on a pixel.

        Args:
            col (tuple | int): if a `tuple` set `color` property and use it to turn on it, if a non-zero `int` turn on the pixel using `color`. If zero, turn off it with `pybox.color.OFF`

        Examples:
            >>> ring.write(1)   # turn on all the ring with current global color
            >>> ring.write(0)   # turn off all the ring
        """
        self.__ring.set_pixel(self.index, col)

    @property
    def color(self) -> tuple[int]:
        """Get/Set color of a pixel.

        Returns:
            color: color of the pixel in `tuple[int]` format
        """
        return self.__ring.get_pixel_color(self.index)

    @color.setter
    def color(self, color: tuple[int]):
        self.__ring.set_pixel_color(self.index, color)

Attributes

color: tuple[int] property writable

Get/Set color of a pixel.

Returns:

  • color ( tuple[int] ) –

    color of the pixel in tuple[int] format

Functions

on()

Turn on a pixel.

Examples:

>>> ring[0].on()   # turn on the pixel at index 0 with current color
Source code in pybox/ring.py 
169
170
171
172
173
174
175
def on(self):
    """Turn on a pixel.

    Examples:
        >>> ring[0].on()   # turn on the pixel at index 0 with current color
    """
    self.__ring.set_pixel(self.index, 1)
off()

Turn off a pixel.

Examples:

>>> ring[0].off()   # turn off the pixel at index 0 with current color
Source code in pybox/ring.py 
177
178
179
180
181
182
183
def off(self):
    """Turn off a pixel.

    Examples:
        >>> ring[0].off()   # turn off the pixel at index 0 with current color
    """
    self.__ring.set_pixel(self.index, 0)
toggle()

Turn on a pixel if the pixel is currently turned off and viceversa.

Source code in pybox/ring.py 
185
186
187
188
189
190
191
def toggle(self):
    """Turn on a pixel if the pixel is currently turned off and viceversa.
    """
    if self.__ring.is_on(self.index):
        self.off()
    else:
        self.on()
write(col: tuple = None) -> None

Write a value on a pixel.

Parameters:

  • col (tuple | int, default: None ) –

    if a tuple set color property and use it to turn on it, if a non-zero int turn on the pixel using color. If zero, turn off it with pybox.color.OFF

Examples:

>>> ring.write(1)   # turn on all the ring with current global color
>>> ring.write(0)   # turn off all the ring
Source code in pybox/ring.py 
193
194
195
196
197
198
199
200
201
202
203
def write(self, col: tuple = None) -> None:
    """Write a value on a pixel.

    Args:
        col (tuple | int): if a `tuple` set `color` property and use it to turn on it, if a non-zero `int` turn on the pixel using `color`. If zero, turn off it with `pybox.color.OFF`

    Examples:
        >>> ring.write(1)   # turn on all the ring with current global color
        >>> ring.write(0)   # turn off all the ring
    """
    self.__ring.set_pixel(self.index, col)

RING

Ring class.

Manage the ring of 12 pixels on board of the pybox

Parameters:

  • color (tuple[int], default: RED ) –

    color in (r, g, b) format, tipically a pybox.color identifier [ Default: pybox.color.RED ].

  • brightness (float, default: 0.25 ) –

    value between 0.0 and 1.0 [ Default: 0.25 ].

Examples:

>>> # turn on the ring in green color
>>> ring = RING(color=GREEN)
>>> ring.write(1)
Source code in pybox/ring.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
class RING:
    """Ring class.

    ---

    Manage the ring of 12 pixels on board of the pybox

    Args:
        color: color in (r, g, b) format, tipically a pybox.color identifier [ *Default*: pybox.color.RED ].
        brightness: value between 0.0 and 1.0 [ *Default*: 0.25 ].

    Examples:
        >>> # turn on the ring in green color
        >>> ring = RING(color=GREEN)
        >>> ring.write(1)
    """

    def __init__(self, color: tuple[int] = RED, brightness: float = 0.25):
        self.__ring = ARING(color=color, brightness=brightness)
        self.strip = [PIXEL(x, ring=self.__ring) for x in range(12)]

    def __repr__(self) -> str:
        return f"RING object with color {self.__ring._global_col}"

    def __getitem__(self, index: int) -> PIXEL:
        """Get PIXEL object at index.

        Args:
            index: Pixel index

        Returns:
            A Pixel object

        Examples:
            >>> ring[0]             # get first Pixel
        """
        return self.strip[index]

    def on(self):
        """Turn on the ring.

        Examples:
            >>> ring.on()   # turn on all the ring with current global color
        """
        self.__ring.on()

    def off(self):
        """Turn off the ring.

        Examples:
            >>> ring.off()   # turn off all the ring with current global color
        """
        self.__ring.off()

    def toggle(self):
        """Turn on the ring globally if the first Pixel is currently turned off and viceversa.
        """
        self.__ring.toggle()

    def write(self, col: tuple = None) -> None:
        """Manage the ring globally. It writes a value (`int` or `tuple`) on the ring (all the pixels).

        Args:
            col (tuple | int): if a `tuple` set `full_color` property and use it to turn on/off the whole Ring, if a non-zero `int` turn on the whole Ring using `full_property`. If zero, turn off it with `pybox.color.OFF`

        Examples:
            >>> ring.write(1)   # turn on the ring with current ring color
            >>> ring.write(0)   # turn off the ring
        """
        self.__ring.write(col)

    def deinit(self) -> None:
        """Blank out the ring and release the pin for other use. 
        """
        self.__ring.deinit()

    @property
    def color(self) -> tuple[int]:
        """Get/Set color of the ring.

        Returns:
            color: color of the ring in `tuple[int]` format
        """
        return self.__ring.color

    @color.setter
    def color(self, color: tuple[int]):
        self.__ring.color = color

    @property
    def brightness(self) -> float:
        """Get/Set color of the ring.

        Returns:
            brightness: brightness of the ring in `float` format
        """
        return self.__ring.brightness

    @brightness.setter
    def brightness(self, value: float):
        self.__ring.brightness = value

Attributes

color: tuple[int] property writable

Get/Set color of the ring.

Returns:

  • color ( tuple[int] ) –

    color of the ring in tuple[int] format

brightness: float property writable

Get/Set color of the ring.

Returns:

  • brightness ( float ) –

    brightness of the ring in float format

Functions

__getitem__(index: int) -> PIXEL

Get PIXEL object at index.

Parameters:

  • index (int) –

    Pixel index

Returns:

  • PIXEL –

    A Pixel object

Examples:

>>> ring[0]             # get first Pixel
Source code in pybox/ring.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
def __getitem__(self, index: int) -> PIXEL:
    """Get PIXEL object at index.

    Args:
        index: Pixel index

    Returns:
        A Pixel object

    Examples:
        >>> ring[0]             # get first Pixel
    """
    return self.strip[index]
on()

Turn on the ring.

Examples:

>>> ring.on()   # turn on all the ring with current global color
Source code in pybox/ring.py 
257
258
259
260
261
262
263
def on(self):
    """Turn on the ring.

    Examples:
        >>> ring.on()   # turn on all the ring with current global color
    """
    self.__ring.on()
off()

Turn off the ring.

Examples:

>>> ring.off()   # turn off all the ring with current global color
Source code in pybox/ring.py 
265
266
267
268
269
270
271
def off(self):
    """Turn off the ring.

    Examples:
        >>> ring.off()   # turn off all the ring with current global color
    """
    self.__ring.off()
toggle()

Turn on the ring globally if the first Pixel is currently turned off and viceversa.

Source code in pybox/ring.py 
273
274
275
276
def toggle(self):
    """Turn on the ring globally if the first Pixel is currently turned off and viceversa.
    """
    self.__ring.toggle()
write(col: tuple = None) -> None

Manage the ring globally. It writes a value (int or tuple) on the ring (all the pixels).

Parameters:

  • col (tuple | int, default: None ) –

    if a tuple set full_color property and use it to turn on/off the whole Ring, if a non-zero int turn on the whole Ring using full_property. If zero, turn off it with pybox.color.OFF

Examples:

>>> ring.write(1)   # turn on the ring with current ring color
>>> ring.write(0)   # turn off the ring
Source code in pybox/ring.py 
278
279
280
281
282
283
284
285
286
287
288
def write(self, col: tuple = None) -> None:
    """Manage the ring globally. It writes a value (`int` or `tuple`) on the ring (all the pixels).

    Args:
        col (tuple | int): if a `tuple` set `full_color` property and use it to turn on/off the whole Ring, if a non-zero `int` turn on the whole Ring using `full_property`. If zero, turn off it with `pybox.color.OFF`

    Examples:
        >>> ring.write(1)   # turn on the ring with current ring color
        >>> ring.write(0)   # turn off the ring
    """
    self.__ring.write(col)
deinit() -> None

Blank out the ring and release the pin for other use.

Source code in pybox/ring.py 
290
291
292
293
def deinit(self) -> None:
    """Blank out the ring and release the pin for other use. 
    """
    self.__ring.deinit()