HandsON-BuildHat-API 1.0__py3-none-any.whl

HandsON_BuildHat_API/SpikePI.py

@@ -0,0 +1,324 @@
+# Encoding      : UTF-8
+# Date          : 2025-04-30
+# Production    : HandsON Technology Co., Ltd
+# Author        : HaNeul Jung (caffeine.reload@gmail.com)
+
+# All rights to the code, excluding third-party libraries used herein, are reserved by HandsON Technology Co., Ltd.
+
+from serial import Serial
+import time
+
+class _ConstModuleID:
+    '''
+    모듈 ID 모음
+    '''
+    COLOR = 0x3D
+    DISTANCE = 0x3E
+    FORCE = 0x3F
+
+    SMALL_MOTOR = 0x41
+    MEDIUM_MOTOR = 0x30
+    LARGE_MOTOR = 0x31
+
+class _ConstValue:
+    '''
+    기타 상수 모음
+    '''
+    COMMAND = 0b1000 << 4
+    GET_DATA = 0b1001 << 4
+    ALL_PORT = 0b1111
+
+    MOTOR_PWM_MODE = 0
+    MOTOR_ABS_MODE = 1
+    MOTOR_REL_MODE = 2
+
+class _PORT:
+    PORT = {
+        'A':0, 'B':1, 'C':2, 'D':3, 'E':4, 'F':5
+    }
+
+class _COLOR:
+    COLOR = {
+        0:'black', 1:'violet', 3:'blue', 4:'cyan', 
+        5:'green', 7:'yellow', 9:'red', 10:'white',
+        255:'None'
+    }
+
+class _Availability:
+    '''
+    내부용 시리얼 통신의 체크섬을 확인 및 체크섬을 만드는 함수를 제공합니다.
+    '''
+    @staticmethod
+    def make_checksum(byte:bytes) -> bytes:
+        '''
+        입력 받은 바이트를 기반으로 체크섬을 만들고 반환합니다.
+        '''
+        sum = 0
+        for i in byte: sum ^= i
+        return bytes([sum])
+    
+    @staticmethod
+    def checksum_check(byte:bytes) -> bool:
+        '''
+        바이트열의 체크섬을 확인하고 불 값을 반환합니다.
+        '''
+        sum = 0
+        for i in byte[:-1]: sum ^= i
+        try:
+            if sum == byte[-1]: return True
+            else: return False
+        except IndexError:
+            return False
+
+class _SerialManager:
+    '''
+    내부용 시리얼 버스 객체, **외부 접근 절대 금지**.
+    '''
+    _serial_port = (
+        '/dev/ttyTHS1', # Jetson Orin Nano
+        '/dev/ttyAMA0', # Raspberry PI 5
+        '/dev/ttyS0'    # Raspberry PI 4
+    )
+    serial = None
+
+    for i in _serial_port:
+        try: serial = Serial(port=i, baudrate=115200, timeout=0.1)
+        except: pass
+        else: break
+
+    if serial == None:
+        raise Exception('사용 가능한 시리얼 포트를 찾을 수 없습니다.')
+
+class _ModuleParent:
+    def _get_data(self, byte:bytes) -> bytes:
+        while True:
+            self._send_data(byte)
+            data = _SerialManager.serial.read(16)
+
+            if data == b'': continue
+
+            if _Availability.checksum_check(data): return data
+
+    def _send_data(self, byte:bytes) -> None:
+        com = byte
+        for i in range(0, 7-len(com)): com += b'\x00'
+        com += _Availability.make_checksum(com)
+        time.sleep(0.005)
+        _SerialManager.serial.write(com)
+
+    def _module_check(self, port:int, ID:tuple) -> None:
+        command = [_ConstValue.GET_DATA + _ConstValue.ALL_PORT]
+        if not self._get_data(byte=bytes(command))[port + 1] in ID:
+            raise Exception('해당 포트에 연결된 모듈이 다르거나 없습니다.')
+
+class ColorSensor(_ModuleParent):
+    def __init__(self, port:str):
+        self._PORT = _PORT.PORT[port]
+        self._module_check(self._PORT, (_ConstModuleID.COLOR, ))
+        
+    def get_color(self) -> str:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return _COLOR.COLOR[data[1]]
+    
+    def get_reflected_light(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return data[2]
+    
+    def get_rgb_intensity(self) -> tuple:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return (data[3] + (data[4] << 8), data[5] + (data[6] << 8), data[7] + (data[8] << 8))
+
+    def get_red(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return data[3] + (data[4] << 8)
+    
+    def get_green(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return data[5] + (data[6] << 8)
+    
+    def get_blue(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return data[7] + (data[8] << 8)
+    
+class DistanceSensor(_ModuleParent):
+    def __init__(self, port:str):
+        self._PORT = _PORT.PORT[port]
+        self._module_check(self._PORT, (_ConstModuleID.DISTANCE, ))
+
+    def get_distance_cm(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return (data[1] + (data[2] << 8)) // 10
+
+class ForceSensor(_ModuleParent):
+    def __init__(self, port:str):
+        self._PORT = _PORT.PORT[port]
+        self._module_check(self._PORT, (_ConstModuleID.FORCE, ))
+
+    def is_pressed(self) -> bool:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        if data[2] == 1: return True
+        else: return False
+
+    def get_force_percentage(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        return data[1]
+
+class Motor(_ModuleParent):
+    def __init__(self, port:str):
+        self._PORT = _PORT.PORT[port]
+        self._module_check(self._PORT, (_ConstModuleID.SMALL_MOTOR, _ConstModuleID.MEDIUM_MOTOR, _ConstModuleID.LARGE_MOTOR))
+
+    def stop(self) -> None:
+        com = bytes((_ConstValue.COMMAND + self._PORT, _ConstValue.MOTOR_PWM_MODE, 0, 0))
+        self._send_data(com)
+
+    def start(self, speed:int) -> None:
+        if not speed in range(-100, 101):
+            raise Exception('모터의 속도는 ~100 ~ 100 사이의 정수만 입력 가능합니다.')
+        
+        if speed > 0: sw = 1
+        else: sw = 0
+
+        com = bytes((_ConstValue.COMMAND + self._PORT, _ConstValue.MOTOR_PWM_MODE, sw, abs(speed)))
+        self._send_data(com)
+
+    def run_to_position(self, degrees, speed) -> None:
+        if not speed in range(0, 101):
+            raise Exception('모터의 속도는 0 ~ 100 사이의 정수만 입력 가능합니다.')
+        if not degrees in range(-180, 181):
+            raise Exception('모터의 절대 각도는 -180 ~ 180 사이의 정수만 입력 가능합니다.')
+        
+        if degrees >= 0: target = degrees
+        else: target = degrees & 0xFFFF
+        
+        com = bytes((_ConstValue.COMMAND + self._PORT, _ConstValue.MOTOR_ABS_MODE, speed, (target & 0xFF), (target >> 8)))
+        self._send_data(com)
+
+    def run_for_degrees(self, degrees, speed) -> None:
+        if not speed in range(0, 101):
+            raise Exception('모터의 속도는 0 ~ 100 사이의 정수만 입력 가능합니다.')
+        
+        if not degrees in range(-2147483647, 2147483647):
+            raise Exception('모터의 동작 각도는 -2147483647 ~ 2147483647 사이의 값만 입력 가능합니다.')
+        
+        if degrees >= 0: target = degrees
+        else: target = degrees & 0xFFFFFFFF
+
+        com = bytes((_ConstValue.COMMAND + self._PORT, _ConstValue.MOTOR_REL_MODE, speed, (target & 0xFF), (target >> 8) & 0xFF, (target >> 16) & 0xFF, (target >> 24) & 0xFF))
+        self._send_data(com)
+
+    def get_speed(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        if data[1] >> 7 == 0: return data[1]
+        else: return -(0xFF - data[1])
+
+    def get_position(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        if data[7] >> 7 == 0: return data[6] + (data[7] << 8)
+        else: return -(0xFFFF - (data[6] + (data[7] << 8) - 1))
+
+    def get_degrees_counted(self) -> int:
+        command = [_ConstValue.GET_DATA + self._PORT]
+        data = self._get_data(bytes(command))
+        if data[5] >> 7 == 0: return data[2] + (data[3] << 8) + (data[4] << 16) + (data[5] << 24)
+        else: return -(0xFFFFFFFF - (data[2] + (data[3] << 8) + (data[4] << 16) + (data[5] << 24) - 1))
+
+class MotorPair(_ModuleParent):
+    def __init__(self, left_motor, right_motor):
+        self._PORTs = (_PORT.PORT[left_motor],  _PORT.PORT[right_motor])
+        for i in self._PORTs: self._module_check(i, (_ConstModuleID.LARGE_MOTOR, _ConstModuleID.MEDIUM_MOTOR, _ConstModuleID.SMALL_MOTOR))
+
+    def stop(self) -> None:
+        for i in self._PORTs:
+            com = bytes((_ConstValue.COMMAND + i, _ConstValue.MOTOR_PWM_MODE, 0, 0))
+            self._send_data(com)
+
+    def start(self, steering, speed) -> None:
+        if not steering in range(-100, 101):
+            raise Exception('조향 값은 -100 ~ 100 사이의 값만 입력 가능합니다.')
+        if not speed in range(-100, 101):
+            raise Exception('속도 값은 -100 ~ 100 사이의 값만 입력 가능합니다.')
+        
+        out = (
+            int((speed + (speed * (steering / 100))) *  1),
+            int((speed - (speed * (steering / 100))) * -1)
+        )
+
+        for motor, speed in zip(self._PORTs, out):
+            if speed > 0: sw = 1
+            else: sw = 0
+
+            com = bytes((_ConstValue.COMMAND + motor, _ConstValue.MOTOR_PWM_MODE, sw, abs(speed)))
+            self._send_data(com)
+
+    def move(self, degrees, steering, speed) -> None:
+        if not steering in range(-100, 101):
+            raise Exception('조향 값은 -100 ~ 100 사이의 값만 입력 가능합니다.')
+        if not speed in range(0, 101):
+            raise Exception('속도 값은 0 ~ 100 사이의 값만 입력 가능합니다.')
+        if not degrees in range(-2147483647, 2147483647):
+            raise Exception('모터의 동작 각도는 -2147483647 ~ 2147483647 사이의 값만 입력 가능합니다.')
+        
+        out = (
+            int(speed + (speed * (steering / 100))),
+            int(speed - (speed * (steering / 100)))
+        )
+
+        for motor, speed, count in zip(self._PORTs, out, (0, 1)):
+
+            if degrees >= 0: target = degrees
+            else: target = degrees & 0xFFFFFFFF
+
+            if count == 1: target = ~target
+
+            com = bytes((_ConstValue.COMMAND + motor, _ConstValue.MOTOR_REL_MODE, speed, (target & 0xFF), (target >> 8) & 0xFF, (target >> 16) & 0xFF, (target >> 24) & 0xFF))
+            self._send_data(com)
+
+
+    def move_tank(self, degrees, left_speed, right_speed) -> None:
+        if not left_speed in range(-100, 101) or not right_speed in range(-100, 101):
+            raise Exception('조향 값은 -100 ~ 100 사이의 값만 입력 가능합니다.')
+        if not degrees in range(-2147483647, 2147483647):
+            raise Exception('모터의 동작 각도는 -2147483647 ~ 2147483647 사이의 값만 입력 가능합니다.')
+
+        out = (
+            int(left_speed  *  1),
+            int(right_speed * -1)
+        )
+
+        for motor, speed, count in zip(self._PORTs, out, (0, 1)):
+
+            if degrees >= 0: target = degrees
+            else: target = degrees & 0xFFFFFFFF
+
+            if count == 1: target = ~target
+
+            com = bytes((_ConstValue.COMMAND + motor, _ConstValue.MOTOR_REL_MODE, speed, (target & 0xFF), (target >> 8) & 0xFF, (target >> 16) & 0xFF, (target >> 24) & 0xFF))
+            self._send_data(com)
+
+    def start_tank(self, left_speed, right_speed) -> None:
+        if not left_speed in range(-100, 101) or not right_speed in range(-100, 101):
+            raise Exception('조향 값은 -100 ~ 100 사이의 값만 입력 가능합니다.')
+
+        out = (
+            int(left_speed  *  1),
+            int(right_speed * -1)
+        )
+
+        for motor, speed in zip(self._PORTs, out):
+            if speed > 0: sw = 1
+            else: sw = 0
+
+            com = bytes((_ConstValue.COMMAND + motor, _ConstValue.MOTOR_PWM_MODE, sw, abs(speed)))
+            self._send_data(com)

HandsON_BuildHat_API/__init__.py

@@ -0,0 +1,4 @@
+
+from .SpikePI import Motor, MotorPair, ColorSensor, DistanceSensor, ForceSensor
+
+__all__ = ['Motor', 'MotorPair', 'ColorSensor', 'DistanceSensor', 'ForceSensor']

handson_buildhat_api-1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: HandsON-BuildHat-API
+Version: 1.0
+Summary: A third-party API for controlling LEGO SPIKE devices
+Author-email: HandsON Technology <caffeine.reload@gmail.com>
+License: Proprietary - Personal/Educational Use Only
+Project-URL: Homepage, https://github.com/yourname/HandsON-BuildHat-API
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Dynamic: license-file
+
+HandsON Build Hat API
+=======
+**Production** : HandsON Technology co., ltd.  
+**Author** : HaNeul Jung (caffeine.reload@gmail.com)  
+**Last Update** : 2025-06-07
+
+## 개요
+제작된 빌드햇의 제어에 필요한 API 라이브러리
+
+## 구동 환경
+### 컨트롤러
+|이름|설명|
+|:--|:--|
+|Raspberry PI 4, 5|정상 동작 확인|
+|Jetson Orin Nano, Nano|정상 동작 확인 (하드웨어 구조가 라즈베리파이 버전과 다름)|
+
+### 종속성
+ - python3-serial
+
+## 예제
+모든 API는 기존 Spike Legacy와 문법적으로 동일  
+
+```python
+from SpikePI import ColorSensor, Motor
+
+motor = Motor('A')
+colorsensor = ColorSensor('B')
+
+reflected = colorsensor.get_reflected_light()
+motor.start(100)
+```
+
+자세한 문법은 Lego Spike Legacy 앱에서 확인

handson_buildhat_api-1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+HandsON_BuildHat_API/SpikePI.py,sha256=L4zmkYZxM1uZjmCVoax0lZ8E9XsBipPLWlbdjQsCsIc,11884
+HandsON_BuildHat_API/__init__.py,sha256=nAmCRGKB6DwSg84Qv3N27Ay34fySDrYj6p3RUMFRImk,162
+handson_buildhat_api-1.0.dist-info/licenses/LICENSE,sha256=xkedyvUIiuPGSXgx2D3uwqfpQ1LLkovfT0zPSAdK6Jg,442
+handson_buildhat_api-1.0.dist-info/METADATA,sha256=k04oav7-OD3I0q4Zcer7oxyXljoGFxnxCKzqeQdbTzA,1367
+handson_buildhat_api-1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+handson_buildhat_api-1.0.dist-info/top_level.txt,sha256=lZyPncSVT9fytRRmtXmZ5bIeg_Xlfmt8-_50B5ib5jU,21
+handson_buildhat_api-1.0.dist-info/RECORD,,

handson_buildhat_api-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

handson_buildhat_api-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2025 HandsON Technology co., ltd.
+
+All rights reserved.
+
+This software is provided for personal and educational use only.  
+You are granted permission to use this software *as-is* without modification.  
+You may not copy, modify, distribute, sublicense, or use this software in any commercial context without explicit written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

handson_buildhat_api-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+HandsON_BuildHat_API