v1.3.0 (divoom api calls, dependency upgrade, minor improvements)

Author: 4ch1m

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.3.0 (2023-01-06)
+
+* new: 'divoom' section (query official [API](https://app.divoom-gz.com))
+* dependency updates
+* other minor improvements
+
 ## 1.2.0 (2022-10-29)
 
 * new environment settings `PIXOO_REST_HOST` and `PIXOO_REST_DEBUG` (see [README](README.md))

README.md

@@ -65,10 +65,9 @@ cd pixoo-rest
 
 ### Init
 
-Initialize the _pixoo_ submodule:
+Update/initialize the _pixoo_ submodule:
 ```bash
-git submodule init
-git submodule update
+git submodule update --init
 ```
 
 ### Configure

_helpers.py

@@ -1,8 +1,11 @@
 import requests
+import json
 
 from datetime import datetime
 from pathlib import Path
 
+divoom_api_url = 'https://app.divoom-gz.com'
+
 
 def parse_bool_value(value):
     if isinstance(value, bool):
@@ -24,6 +27,33 @@ def get_swagger_config():
     }
 
 
+def get_additional_swagger_template():
+    return {
+        'tags': [
+            {
+                'name': 'draw',
+                'description': 'draw lines, pixels, rectangles, etc. on your Pixoo'
+            },
+            {
+                'name': 'send',
+                'description': 'send text, GIFs, etc. to your Pixoo'
+            },
+            {
+                'name': 'set',
+                'description': 'set brightness, channel, clock, etc. on your Pixoo'
+            },
+            {
+                'name': 'pass-through',
+                'description': "directly pass commands to your Pixoo's built-in HTTP-API"
+            },
+            {
+                'name': 'divoom',
+                'description': f'send requests to the external vendor API ({divoom_api_url})'
+            }
+        ]
+    }
+
+
 def try_to_request(url):
     try:
         print(f'[ {datetime.now().strftime("%Y-%m-%d (%H:%M:%S)")} ] Trying to request "{url}" ... ', end='')
@@ -34,3 +64,10 @@ def try_to_request(url):
     except:
         print('FAILED.')
         return False
+
+
+def divoom_api_call(endpoint, payload=None):
+    return requests.post(
+        f'{divoom_api_url}/{endpoint}',
+        json.dumps(payload)
+    )

app.py

@@ -13,31 +13,32 @@
 from swag import definitions
 from swag import passthrough
 
-from _helpers import parse_bool_value, get_swagger_config, try_to_request
+import _helpers
 
 load_dotenv()
 
 pixoo_host = os.environ.get('PIXOO_HOST', 'Pixoo64')
-pixoo_debug = parse_bool_value(os.environ.get('PIXOO_DEBUG', 'false'))
+pixoo_screen = int(os.environ.get('PIXOO_SCREEN_SIZE', 64))
+pixoo_debug = _helpers.parse_bool_value(os.environ.get('PIXOO_DEBUG', 'false'))
 
-while not try_to_request(f'http://{pixoo_host}/get'):
+while not _helpers.try_to_request(f'http://{pixoo_host}/get'):
     time.sleep(30)
 
 pixoo = Pixoo(
     pixoo_host,
-    int(os.environ.get('PIXOO_SCREEN_SIZE', 64)),
+    pixoo_screen,
     pixoo_debug
 )
 
 app = Flask(__name__)
-app.config['SWAGGER'] = get_swagger_config()
+app.config['SWAGGER'] = _helpers.get_swagger_config()
 
-swagger = Swagger(app)
+swagger = Swagger(app, template=_helpers.get_additional_swagger_template())
 definitions.create(swagger)
 
 
 def _push_immediately(_request):
-    if parse_bool_value(_request.form.get('push_immediately', default=True)):
+    if _helpers.parse_bool_value(_request.form.get('push_immediately', default=True)):
         pixoo.push()
 
 
@@ -76,7 +77,7 @@ def generic_set_number(number):
 @swag_from('swag/set/generic_boolean.yml')
 def generic_set_boolean(boolean):
     if request.path.startswith('/screen/on/'):
-        pixoo.set_screen(parse_bool_value(boolean))
+        pixoo.set_screen(_helpers.parse_bool_value(boolean))
 
     return 'OK'
 
@@ -235,7 +236,7 @@ def _send_gif(num, offset, width, speed, data):
 def send_gif():
     gif = Image.open(request.files['gif'].stream)
     speed = int(request.form.get('speed'))
-    skip_first_frame = parse_bool_value(request.form.get('skip_first_frame', default=False))
+    skip_first_frame = _helpers.parse_bool_value(request.form.get('skip_first_frame', default=False))
 
     if gif.is_animated:
         _reset_gif()
@@ -312,9 +313,33 @@ def passthrough_{list(passthrough_routes.keys()).index(_route)}():
         """)
 
 
+@app.route('/divoom/device/lan', methods=['POST'])
+@swag_from('swag/divoom/device/return_same_lan_device.yml')
+def divoom_return_same_lan_device():
+    return _helpers.divoom_api_call('Device/ReturnSameLANDevice').json()
+
+
+@app.route('/divoom/channel/dial/types', methods=['POST'])
+@swag_from('swag/divoom/channel/get_dial_type.yml')
+def divoom_get_dial_type():
+    return _helpers.divoom_api_call('Channel/GetDialType').json()
+
+
+@app.route('/divoom/channel/dial/list', methods=['POST'])
+@swag_from('swag/divoom/channel/get_dial_list.yml')
+def divoom_get_dial_list():
+    return _helpers.divoom_api_call(
+        'Channel/GetDialList',
+        {
+            'DialType': request.form.get('dial_type', default='Game'),
+            'Page': int(request.form.get('page_number', default='1'))
+        }
+    ).json()
+
+
 if __name__ == '__main__':
     app.run(
-        debug=parse_bool_value(os.environ.get('PIXOO_REST_DEBUG', 'false')),
+        debug=_helpers.parse_bool_value(os.environ.get('PIXOO_REST_DEBUG', 'false')),
         host=os.environ.get('PIXOO_REST_HOST', '127.0.0.1'),
         port=os.environ.get('PIXOO_REST_PORT', '5000')
     )

requirements.txt

@@ -2,5 +2,5 @@ python-dotenv==0.21.0
 Flask==2.2.2
 flasgger==0.9.5
 requests==2.28.1
-Pillow==9.2.0
+Pillow==9.4.0
 gunicorn==20.1.0

swag/divoom/channel/get_dial_list.yml

@@ -0,0 +1,23 @@
+description: Get a list of all 'dial' elements.
+
+parameters:
+  - name: dial_type
+    description: The dial type.
+    in: formData
+    type: string
+    default: Game
+    required: true
+  - name: page_number
+    description: 'The page number. (Note: Each page contains 30 items.)'
+    in: formData
+    type: integer
+    minimum: 1
+    default: 1
+    required: true
+
+responses:
+  '200':
+    description: OK
+
+tags:
+  - divoom

swag/divoom/channel/get_dial_type.yml

@@ -0,0 +1,8 @@
+description: Get a list of all 'dial' types.
+
+responses:
+  '200':
+    description: OK
+
+tags:
+  - divoom

swag/divoom/device/return_same_lan_device.yml

@@ -0,0 +1,8 @@
+description: Get a list of all (Pixoo-)devices in your local network.
+
+responses:
+  '200':
+    description: OK
+
+tags:
+  - divoom

swag/send/gif.yml

@@ -1,4 +1,5 @@
-description: "NOTE: The GIF should have max 60 animation frames."
+description: 'NOTE: The GIF should have max 60 animation frames.'
+
 parameters:
   - name: gif
     description: The animated GIF image to display. (Automatically gets resized.)

swag/send/text.yml

@@ -1,4 +1,5 @@
 description: "NOTE: This way of sending text to the device seems unreliable atm. The 'draw text' method is a better alternative."
+
 parameters:
   - name: text
     description: The text to display.

version.txt

@@ -1 +1 @@
-1.2.0
+1.3.0