Feature(escpos) Add buzzer function (#535)

* Add buzzer function
* Add `buzzer(time, duration)` function to control the buzzer on supported
   printers.
* Add unit tests for buzzer function.
* Update test_function_buzzer.py to pass black
* Run black in tests files
---------

Co-authored-by: Patrick Kanzler <dev@pkanzler.de>

.mailmap

@@ -17,3 +17,4 @@ Alex Debiasio <alex.debiasio@thinkin.io>             <alex.debiasio@studenti.uni
 Maximilian Wagenbach <maximilian.wagenbach@native-instruments.de>
 <belono@users.noreply.github.com>                    <tiotil.lindeman@gmail.com>
 belono <belono@users.noreply.github.com>             Benito López <belono@users.noreply.github.com>
+Alfredo Orozco <alfredoopa@gmail.com>                Alfredo orozco <alfreedom@users.noreply.github.com>

AUTHORS

@@ -3,6 +3,7 @@ akeonly
 Alejandro Hernández
 Alexander Bougakov
 Alex Debiasio
+Alfredo Orozco
 Asuki Kono
 belono
 B. Howell
@@ -15,6 +16,7 @@ Davis Goglin
 Dean Rispin
 dependabot[bot]
 Dmytro Katyukha
+Florent de Labarre
 Gerard Marull-Paretas
 Hark
 Joel Lehtonen
@@ -37,12 +39,14 @@ Qian Linfeng
 Ramon Poca
 reck31
 Renato Lorenzi
+Ricardo Sánchez Alba
 Romain Porte
 Sam Cheng
 Sergio Pulgarin
 Stephan Sokolow
 Thijs Triemstra
 Thomas van den Berg
+vendryan
 Yaisel Hurtado
 ysuolmai
 白月秋见心

src/escpos/constants.py

@@ -63,6 +63,9 @@ PAPER_PART_CUT = _CUT_PAPER(b"\x01")  #: Partial cut paper
 # Beep (please note that the actual beep sequence may differ between devices)
 BEEP = b"\x07"
 
+# Internal buzzer (only supported printers)
+BUZZER = ESC + b"\x42"
+
 # Panel buttons (e.g. the FEED button)
 _PANEL_BUTTON = lambda n: ESC + b"c5" + six.int2byte(n)
 PANEL_BUTTON_ON = _PANEL_BUTTON(0)  # enable all panel buttons

src/escpos/escpos.py

@@ -58,6 +58,7 @@ from .constants import (
     CD_KICK_2,
     PAPER_FULL_CUT,
     PAPER_PART_CUT,
+    BUZZER,
 )
 from .constants import HW_RESET, HW_SELECT, HW_INIT
 from .constants import (
@@ -1243,6 +1244,24 @@ class Escpos(object):
         """
         self._raw(SLIP_SELECT)
 
+    def buzzer(self, times=2, duration=4):
+        """Activate the internal printer buzzer (only supported printers).
+
+        The 'times' parameter refers to the 'n' escpos command parameter,
+        which means how many times the buzzer will be 'beeped'.
+
+        :param times: Integer between 1 and 9, indicates the buzzer beeps.
+        :param duration: Integer between 1 and 9, indicates the beep duration.
+        :returns: None
+        """
+
+        if not 1 <= times <= 9:
+            raise ValueError("times must be between 1 and 9")
+        if not 1 <= duration <= 9:
+            raise ValueError("duration must be between 1 and 9")
+
+        self._raw(BUZZER + six.int2byte(times) + six.int2byte(duration))
+
 
 class EscposIO(object):
     """ESC/POS Printer IO object

test/test_function_buzzer.py

@@ -0,0 +1,54 @@
+import six
+import pytest
+
+from escpos import printer
+from escpos.constants import BUZZER
+
+
+def test_buzzer_function_with_default_params():
+    instance = printer.Dummy()
+    instance.buzzer()
+    expected = BUZZER + six.int2byte(2) + six.int2byte(4)
+    assert instance.output == expected
+
+
+@pytest.mark.parametrize(
+    "times, duration",
+    [
+        [1, 1],
+        [2, 2],
+        [3, 3],
+        [4, 4],
+        [5, 5],
+        [6, 6],
+        [7, 7],
+        [8, 8],
+        [9, 9],
+    ],
+)
+def test_buzzer_function(times, duration):
+    instance = printer.Dummy()
+    instance.buzzer(times, duration)
+    expected = BUZZER + six.int2byte(times) + six.int2byte(duration)
+    assert instance.output == expected
+
+
+@pytest.mark.parametrize(
+    "times, duration, expected_message",
+    [
+        [0, 0, "times must be between 1 and 9"],
+        [-1, 0, "times must be between 1 and 9"],
+        [10, 0, "times must be between 1 and 9"],
+        [11, 0, "times must be between 1 and 9"],
+        [3, 0, "duration must be between 1 and 9"],
+        [3, -1, "duration must be between 1 and 9"],
+        [3, 10, "duration must be between 1 and 9"],
+        [3, 11, "duration must be between 1 and 9"],
+    ],
+)
+def test_buzzer_fuction_with_outrange_values(times, duration, expected_message):
+    instance = printer.Dummy()
+    with pytest.raises(ValueError) as e:
+        instance.buzzer(times, duration)
+
+    assert str(e.value) == expected_message