From c10242c09d1a063892415aeaf34a392271c83496 Mon Sep 17 00:00:00 2001
From: Alfredo Orozco <alfredoopa@gmail.com>
Date: Mon, 24 Jul 2023 22:30:59 -0600
Subject: [PATCH] ture(escpos) Add buzzer function

- Add `buzzer(time, duration)` function to control the buzzer on supported
printers.
- Add unit tests for buzzer function.
---
 AUTHORS                      |  1 +
 src/escpos/constants.py      |  3 +++
 src/escpos/escpos.py         | 19 +++++++++++++++
 test/test_function_buzzer.py | 46 ++++++++++++++++++++++++++++++++++++
 4 files changed, 69 insertions(+)
 create mode 100644 test/test_function_buzzer.py

diff --git a/AUTHORS b/AUTHORS
index 53fa617..65be0d8 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -3,6 +3,7 @@ akeonly
 Alejandro Hernández
 Alex Debiasio
 Alexander Bougakov
+Alfredo Orozco
 Asuki Kono
 B. Howell
 belono
diff --git a/src/escpos/constants.py b/src/escpos/constants.py
index 2fd0820..dc2704f 100644
--- a/src/escpos/constants.py
+++ b/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
diff --git a/src/escpos/escpos.py b/src/escpos/escpos.py
index 4dbe08e..ebd405e 100644
--- a/src/escpos/escpos.py
+++ b/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' paramreffers to the 'n' escpos command parameter, 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
diff --git a/test/test_function_buzzer.py b/test/test_function_buzzer.py
new file mode 100644
index 0000000..eb98613
--- /dev/null
+++ b/test/test_function_buzzer.py
@@ -0,0 +1,46 @@
+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