jacarev3 0.1.0__tar.gz

jacarev3-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ítalo Vinicius Barbosa Felix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jacarev3-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: jacarev3
+Version: 0.1.0
+Summary: Lib em português pra controlar o LEGO EV3 via Bluetooth — protocolo Direct Commands implementado do zero, sem dependências externas
+Author: Ítalo Vinicius Barbosa Felix
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/i-barbosa/jacarEV3
+Project-URL: Repository, https://github.com/i-barbosa/jacarEV3
+Project-URL: Issues, https://github.com/i-barbosa/jacarEV3/issues
+Project-URL: Changelog, https://github.com/i-barbosa/jacarEV3/blob/main/CHANGELOG.md
+Keywords: ev3,lego,mindstorms,robotica,bluetooth,educacional
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Hardware
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jacarEV3 🐊
+
+Lib em português pra controlar o LEGO EV3 via Bluetooth. Sem dependências
+externas — só biblioteca padrão do Python.
+
+[![PyPI](https://img.shields.io/pypi/v/jacarev3)](https://pypi.org/project/jacarev3/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Instalação
+
+```bash
+pip install jacarev3
+```
+
+Ou pra desenvolver localmente:
+
+```bash
+git clone https://github.com/i-barbosa/jacarEV3.git
+cd jacarEV3
+pip install -e . --break-system-packages
+```
+
+## Uso rápido
+
+```python
+from jacarev3 import RoboEV3
+
+robo = RoboEV3('00:16:53:64:F8:B8')  # MAC do seu EV3
+
+robo.apitar()
+robo.led('VERDE')
+
+robo.testar_tudo()  # testa motores A-D e sensores 1-4
+
+robo.fechar()
+```
+
+Ou com `with` (fecha a conexão sozinho):
+
+```python
+with RoboEV3('00:16:53:64:F8:B8') as robo:
+    robo.apitar()
+    robo.testar_motores()
+```
+
+## Exemplos por funcionalidade
+
+### Som
+
+```python
+robo.apitar()                                  # bip padrão
+robo.apitar(frequencia=880, duracao_ms=300)    # agudo e curto
+robo.apitar(volume=5)                          # mais alto (1-100)
+```
+
+### LED
+
+```python
+robo.led('VERDE')
+robo.led('VERMELHO_PISCA')
+robo.led('DESLIGADO')
+```
+
+### Motor
+
+```python
+# Gira pra frente 1s, velocidade 30%
+robo.girar_motor('A', velocidade=30, duracao_ms=1000)
+
+# Gira pra trás (velocidade negativa)
+robo.girar_motor('A', velocidade=-30, duracao_ms=1000)
+
+# Solta o motor sem frear (roda livre)
+robo.parar_motor('A', frear=False)
+
+# Testa um motor específico
+robo.testar_motor('B')
+
+# Testa A, B, C, D de uma vez (pula os vazios com aviso)
+robo.testar_motores()
+```
+
+### Sensores
+
+```python
+# Cada teste espera o valor MUDAR de verdade antes de seguir
+# (aproxima algo do ultrassônico, aperta o toque, muda a cor)
+robo.testar_ultrassonico(porta=1)
+robo.testar_toque(porta=2)
+robo.testar_cor(porta=3)
+
+# Testa só alguns tipos, tempo de espera customizado
+robo.testar_sensores(tipos=('toque', 'cor'), tempo_limite=10)
+```
+
+## API completa
+
+### Som e LED
+| Método | Descrição |
+|---|---|
+| `apitar(frequencia=440, duracao_ms=500, volume=1)` | Toca um bip |
+| `led(cor)` | `VERDE`, `VERMELHO`, `AMBAR`, `DESLIGADO`, e variantes `_PISCA` / `_PULSA` |
+
+### Motores (portas A-D)
+| Método | Descrição |
+|---|---|
+| `girar_motor(porta, velocidade=30, duracao_ms=1000, frear=True)` | Velocidade de -100 a 100 |
+| `parar_motor(porta, frear=True)` | Para o motor |
+| `testar_motor(porta)` | Testa um motor específico |
+| `testar_motores()` | Testa A, B, C, D de uma vez |
+
+### Sensores (portas 1-4)
+| Método | Descrição |
+|---|---|
+| `testar_ultrassonico(porta, tempo_limite=15)` | Espera a distância mudar |
+| `testar_toque(porta, tempo_limite=15)` | Espera pressionado/solto |
+| `testar_cor(porta, tempo_limite=15)` | Espera a cor mudar |
+| `testar_sensores(tipos=(...), tempo_limite=15)` | Testa os 3 tipos nas 4 portas |
+| `testar_tudo(tempo_limite=15)` | Motores + todos os sensores |
+
+## Troubleshooting
+
+**`OSError` / timeout ao conectar**
+Confirma que o EV3 tá pareado nas Configurações Bluetooth do Windows/Linux
+e que o Bluetooth dele tá visível/ligado antes de rodar o script.
+
+**`[AVISO] Sem motor (ou erro) na porta X`**
+Normal se não tiver motor físico conectado nessa porta — o método pula e
+segue pros outros.
+
+**`speed must be in range [1-100]`**
+Velocidade tem que ser um valor entre -100 e 100 (direção pelo sinal, não
+por valores fora do range).
+
+**`EV3 respondeu com erro pro comando`**
+Geralmente é modo/porta errada no sensor (ex: pedir leitura de cor num
+sensor de toque). Confere se o sensor físico bate com o tipo do método
+chamado.
+
+## Status
+
+v0.1.0 — protocolo validado byte a byte contra a documentação oficial da
+LEGO (Communication Developer Kit), ainda em bateria de testes no robô
+físico. Veja [CHANGELOG.md](CHANGELOG.md) pro histórico de versões.
+
+## Contribuindo
+
+Issues e PRs são bem-vindos em
+[github.com/i-barbosa/jacarEV3](https://github.com/i-barbosa/jacarEV3).
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

jacarev3-0.1.0/README.md

@@ -0,0 +1,153 @@
+# jacarEV3 🐊
+
+Lib em português pra controlar o LEGO EV3 via Bluetooth. Sem dependências
+externas — só biblioteca padrão do Python.
+
+[![PyPI](https://img.shields.io/pypi/v/jacarev3)](https://pypi.org/project/jacarev3/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Instalação
+
+```bash
+pip install jacarev3
+```
+
+Ou pra desenvolver localmente:
+
+```bash
+git clone https://github.com/i-barbosa/jacarEV3.git
+cd jacarEV3
+pip install -e . --break-system-packages
+```
+
+## Uso rápido
+
+```python
+from jacarev3 import RoboEV3
+
+robo = RoboEV3('00:16:53:64:F8:B8')  # MAC do seu EV3
+
+robo.apitar()
+robo.led('VERDE')
+
+robo.testar_tudo()  # testa motores A-D e sensores 1-4
+
+robo.fechar()
+```
+
+Ou com `with` (fecha a conexão sozinho):
+
+```python
+with RoboEV3('00:16:53:64:F8:B8') as robo:
+    robo.apitar()
+    robo.testar_motores()
+```
+
+## Exemplos por funcionalidade
+
+### Som
+
+```python
+robo.apitar()                                  # bip padrão
+robo.apitar(frequencia=880, duracao_ms=300)    # agudo e curto
+robo.apitar(volume=5)                          # mais alto (1-100)
+```
+
+### LED
+
+```python
+robo.led('VERDE')
+robo.led('VERMELHO_PISCA')
+robo.led('DESLIGADO')
+```
+
+### Motor
+
+```python
+# Gira pra frente 1s, velocidade 30%
+robo.girar_motor('A', velocidade=30, duracao_ms=1000)
+
+# Gira pra trás (velocidade negativa)
+robo.girar_motor('A', velocidade=-30, duracao_ms=1000)
+
+# Solta o motor sem frear (roda livre)
+robo.parar_motor('A', frear=False)
+
+# Testa um motor específico
+robo.testar_motor('B')
+
+# Testa A, B, C, D de uma vez (pula os vazios com aviso)
+robo.testar_motores()
+```
+
+### Sensores
+
+```python
+# Cada teste espera o valor MUDAR de verdade antes de seguir
+# (aproxima algo do ultrassônico, aperta o toque, muda a cor)
+robo.testar_ultrassonico(porta=1)
+robo.testar_toque(porta=2)
+robo.testar_cor(porta=3)
+
+# Testa só alguns tipos, tempo de espera customizado
+robo.testar_sensores(tipos=('toque', 'cor'), tempo_limite=10)
+```
+
+## API completa
+
+### Som e LED
+| Método | Descrição |
+|---|---|
+| `apitar(frequencia=440, duracao_ms=500, volume=1)` | Toca um bip |
+| `led(cor)` | `VERDE`, `VERMELHO`, `AMBAR`, `DESLIGADO`, e variantes `_PISCA` / `_PULSA` |
+
+### Motores (portas A-D)
+| Método | Descrição |
+|---|---|
+| `girar_motor(porta, velocidade=30, duracao_ms=1000, frear=True)` | Velocidade de -100 a 100 |
+| `parar_motor(porta, frear=True)` | Para o motor |
+| `testar_motor(porta)` | Testa um motor específico |
+| `testar_motores()` | Testa A, B, C, D de uma vez |
+
+### Sensores (portas 1-4)
+| Método | Descrição |
+|---|---|
+| `testar_ultrassonico(porta, tempo_limite=15)` | Espera a distância mudar |
+| `testar_toque(porta, tempo_limite=15)` | Espera pressionado/solto |
+| `testar_cor(porta, tempo_limite=15)` | Espera a cor mudar |
+| `testar_sensores(tipos=(...), tempo_limite=15)` | Testa os 3 tipos nas 4 portas |
+| `testar_tudo(tempo_limite=15)` | Motores + todos os sensores |
+
+## Troubleshooting
+
+**`OSError` / timeout ao conectar**
+Confirma que o EV3 tá pareado nas Configurações Bluetooth do Windows/Linux
+e que o Bluetooth dele tá visível/ligado antes de rodar o script.
+
+**`[AVISO] Sem motor (ou erro) na porta X`**
+Normal se não tiver motor físico conectado nessa porta — o método pula e
+segue pros outros.
+
+**`speed must be in range [1-100]`**
+Velocidade tem que ser um valor entre -100 e 100 (direção pelo sinal, não
+por valores fora do range).
+
+**`EV3 respondeu com erro pro comando`**
+Geralmente é modo/porta errada no sensor (ex: pedir leitura de cor num
+sensor de toque). Confere se o sensor físico bate com o tipo do método
+chamado.
+
+## Status
+
+v0.1.0 — protocolo validado byte a byte contra a documentação oficial da
+LEGO (Communication Developer Kit), ainda em bateria de testes no robô
+físico. Veja [CHANGELOG.md](CHANGELOG.md) pro histórico de versões.
+
+## Contribuindo
+
+Issues e PRs são bem-vindos em
+[github.com/i-barbosa/jacarEV3](https://github.com/i-barbosa/jacarEV3).
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

jacarev3-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jacarev3"
+version = "0.1.0"
+description = "Lib em português pra controlar o LEGO EV3 via Bluetooth — protocolo Direct Commands implementado do zero, sem dependências externas"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Ítalo Vinicius Barbosa Felix" }
+]
+keywords = ["ev3", "lego", "mindstorms", "robotica", "bluetooth", "educacional"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Education",
+    "Topic :: System :: Hardware",
+    "Natural Language :: Portuguese (Brazilian)",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/i-barbosa/jacarEV3"
+Repository = "https://github.com/i-barbosa/jacarEV3"
+Issues = "https://github.com/i-barbosa/jacarEV3/issues"
+Changelog = "https://github.com/i-barbosa/jacarEV3/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

jacarev3-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jacarev3-0.1.0/src/jacarev3/__init__.py

@@ -0,0 +1,4 @@
+from .robo import RoboEV3
+
+__all__ = ["RoboEV3"]
+__version__ = "0.1.0"

jacarev3-0.1.0/src/jacarev3/conexao.py

@@ -0,0 +1,55 @@
+"""
+jacarev3.conexao
+--------------
+Transporte de baixo nível: abre um socket Bluetooth clássico (RFCOMM) com o
+EV3 e manda/recebe os pacotes crus montados pelo módulo `protocolo`.
+
+Usa só a biblioteca padrão do Python (`socket` com AF_BLUETOOTH), sem
+dependência externa — funciona no Windows (10+) e no Linux com BlueZ.
+"""
+
+import socket
+import itertools
+
+
+class ConexaoBluetooth:
+    """Conexão RFCOMM clássica com o EV3 (a mesma usada pelo app oficial)."""
+
+    CANAL_RFCOMM_PADRAO = 1
+
+    def __init__(self, mac, canal=None, timeout=10):
+        self.mac = mac
+        self.canal = canal or self.CANAL_RFCOMM_PADRAO
+        self._contador = itertools.count(1)
+        self.socket = socket.socket(
+            socket.AF_BLUETOOTH, socket.SOCK_STREAM, socket.BTPROTO_RFCOMM
+        )
+        self.socket.settimeout(timeout)
+        self.socket.connect((self.mac, self.canal))
+
+    def proximo_contador(self):
+        return next(self._contador) & 0xFFFF
+
+    def enviar(self, pacote):
+        self.socket.send(pacote)
+
+    def receber(self, tamanho_max=1024):
+        return self.socket.recv(tamanho_max)
+
+    def fechar(self):
+        try:
+            self.socket.close()
+        except OSError:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.fechar()
+
+
+# Espaço reservado pra outros transportes (WiFi/USB) no futuro:
+#   ConexaoWiFi   -> socket TCP na porta 5555 + handshake de "unlock"
+#   ConexaoUSB    -> via pyusb, endpoints bulk do EV3 (vendor/product id
+#                    conhecidos: 0x0694 / 0x0005)

jacarev3-0.1.0/src/jacarev3/protocolo.py

@@ -0,0 +1,169 @@
+"""
+jacarev3.protocolo
+-----------------
+Implementação própria do protocolo "Direct Commands" do EV3, escrita do zero
+a partir de duas fontes públicas e oficiais da LEGO:
+
+  1. "LEGO MINDSTORMS EV3 Communication Developer Kit" (PDF oficial da LEGO,
+     documenta o formato dos pacotes e dá exemplos de bytes reais).
+  2. bytecodes.h — cabeçalho oficial do firmware EV3, publicado pela LEGO em
+     github.com/mindboards/ev3sources (lista os opcodes da VM).
+
+Não copia código de nenhuma lib de terceiro (como o ev3_dc, que é GPLv3) —
+só reimplementa o protocolo público documentado pela própria fabricante,
+do mesmo jeito que dezenas de outras libs independentes (ev3dev-lang-python,
+Rust ev3-dc, etc.) já fizeram, cada uma com sua própria licença.
+
+Formato de um Direct Command (confirmado byte a byte no PDF oficial):
+  byte 0-1: tamanho do comando (little endian, sem contar esses 2 bytes)
+  byte 2-3: contador de mensagem (little endian)
+  byte 4:   tipo (0x00 = com resposta, 0x80 = sem resposta)
+  byte 5-6: alocação de variáveis globais/locais (empacotado)
+  byte 7+:  bytecode do comando
+
+Resposta:
+  byte 0-1: tamanho (LE)
+  byte 2-3: contador (LE, igual ao do comando)
+  byte 4:   tipo (0x02 = OK, 0x04 = erro)
+  byte 5+:  buffer de variáveis globais (o que você pediu pra devolver)
+"""
+
+import struct
+
+DIRECT_COMMAND_REPLY = 0x00
+DIRECT_COMMAND_NO_REPLY = 0x80
+DIRECT_REPLY_OK = 0x02
+DIRECT_REPLY_ERROR = 0x04
+
+
+# ---------- Codificação de parâmetros (primitivos LC/GV) ----------
+# Confirmado no PDF oficial: LC0 = valor direto (1 byte), LC1 = prefixo 0x81 +
+# 1 byte, LC2 = prefixo 0x82 + 2 bytes LE, LC4 = prefixo 0x83 + 4 bytes LE,
+# LCS = prefixo 0x84 + string terminada em zero.
+# GV0 (variável global curta) = 0x60 | índice — confirmado batendo com os
+# bytes de exemplo do PDF (leitura de sensor devolvendo em GV0(0) = byte 0x60).
+
+def lc0(v):
+    return bytes([v & 0x3F])
+
+
+def lc1(v):
+    return bytes([0x81]) + struct.pack('<b', v)
+
+
+def lc2(v):
+    return bytes([0x82]) + struct.pack('<h', v)
+
+
+def lc4(v):
+    return bytes([0x83]) + struct.pack('<i', v)
+
+
+def lcs(texto):
+    return bytes([0x84]) + texto.encode('ascii') + b'\x00'
+
+
+def gv0(indice):
+    return bytes([0x60 | (indice & 0x1F)])
+
+
+def lc_auto(v):
+    """Escolhe automaticamente o menor encoding que cabe o valor."""
+    if -32 <= v <= 31:
+        return lc0(v)
+    if -128 <= v <= 127:
+        return lc1(v)
+    if -32768 <= v <= 32767:
+        return lc2(v)
+    return lc4(v)
+
+
+# ---------- Opcodes (de bytecodes.h, header oficial da LEGO) ----------
+
+opSOUND = 0x94
+opUI_WRITE = 0x82
+opINPUT_DEVICE = 0x99
+opOUTPUT_STOP = 0xA3
+opOUTPUT_STEP_SPEED = 0xAE
+opOUTPUT_TIME_SPEED = 0xAF
+
+# Sub-códigos de opSOUND
+SOUND_BREAK = 0
+SOUND_TONE = 1
+
+# Sub-código de opUI_WRITE
+UI_WRITE_LED = 27
+
+# Sub-códigos de opINPUT_DEVICE
+INPUT_READY_RAW = 28
+INPUT_READY_SI = 29
+INPUT_CLR_CHANGES = 26
+
+# Portas de motor (bitmask, confirmado nos bytes de exemplo do PDF)
+PORTA_A = 0x01
+PORTA_B = 0x02
+PORTA_C = 0x04
+PORTA_D = 0x08
+
+# Ação de parada de motor
+PARAR_COAST = 0
+PARAR_BRAKE = 1
+
+# Cores de LED (0-9, da UI_WRITE_SUBCODE)
+LED_PRETO = 0
+LED_VERDE = 1
+LED_VERMELHO = 2
+LED_AMBAR = 3
+LED_VERDE_PISCA = 4
+LED_VERMELHO_PISCA = 5
+LED_AMBAR_PISCA = 6
+LED_VERDE_PULSA = 7
+LED_VERMELHO_PULSA = 8
+LED_AMBAR_PULSA = 9
+
+# Modos de sensor mais usados (públicos, mesmos valores usados por
+# ev3dev/ev3-g e outras implementações independentes)
+MODO_TOQUE = 0            # 0 = solto, 1 = pressionado
+MODO_ULTRASSONICO_CM = 0  # distância em cm
+MODO_COR_REFLETIDA = 0
+MODO_COR_AMBIENTE = 1
+MODO_COR_COR = 2          # 0-7: nenhuma, preto, azul, verde, amarelo, vermelho, branco, marrom
+
+
+class Comando:
+    """Monta um Direct Command byte a byte."""
+
+    def __init__(self):
+        self.bytecode = b''
+
+    def add(self, *partes):
+        for p in partes:
+            self.bytecode += p if isinstance(p, (bytes, bytearray)) else bytes([p])
+        return self
+
+    def montar(self, contador, com_resposta=False, bytes_globais=0):
+        tipo = DIRECT_COMMAND_REPLY if com_resposta else DIRECT_COMMAND_NO_REPLY
+        # aloca variáveis globais: 10 bits, byte5 = bits baixos, byte6 bits 0-1 = bits altos
+        header_vars = bytes([
+            bytes_globais & 0xFF,
+            (bytes_globais >> 8) & 0x03,
+        ])
+        corpo = bytes([tipo]) + header_vars + self.bytecode
+        # "tamanho" no protocolo EV3 conta o contador (2 bytes) + corpo,
+        # excluindo só os 2 bytes do próprio campo de tamanho.
+        tamanho = 2 + len(corpo)
+        return struct.pack('<HH', tamanho, contador) + corpo
+
+
+def parse_resposta(dados):
+    """Retorna (contador, ok, payload) de uma resposta do EV3."""
+    if len(dados) < 5:
+        raise ValueError("Resposta curta demais")
+    tamanho, contador, tipo = struct.unpack('<HHB', dados[:5])
+    ok = (tipo == DIRECT_REPLY_OK)
+    payload = dados[5:5 + tamanho - 3]
+    return contador, ok, payload
+
+
+def ler_float(payload, offset=0):
+    return struct.unpack_from('<f', payload, offset)[0]

jacarev3-0.1.0/src/jacarev3/robo.py

@@ -0,0 +1,206 @@
+"""
+jacarev3.robo
+-----------
+RoboEV3 — mesma API de antes (apitar, led, testar_motores, testar_sensores...)
+mas agora rodando 100% no protocolo próprio (protocolo.py + conexao.py),
+sem depender do pacote `ev3_dc` (GPLv3).
+
+AVISO: primeira versão escrita do zero — os opcodes vêm da documentação
+oficial da LEGO, mas ainda não foi validada em bateria extensa no robô
+físico. Testa com calma e reporta qualquer comportamento estranho.
+"""
+
+import time
+import struct
+
+from . import protocolo as p
+from .conexao import ConexaoBluetooth
+
+CORES_SENSOR = {
+    0: 'nenhuma', 1: 'preto', 2: 'azul', 3: 'verde', 4: 'amarelo',
+    5: 'vermelho', 6: 'branco', 7: 'marrom',
+}
+
+CODIGOS_LED = {
+    'PRETO': p.LED_PRETO, 'DESLIGADO': p.LED_PRETO, 'OFF': p.LED_PRETO,
+    'VERDE': p.LED_VERDE,
+    'VERMELHO': p.LED_VERMELHO,
+    'AMBAR': p.LED_AMBAR, 'LARANJA': p.LED_AMBAR,
+    'VERDE_PISCA': p.LED_VERDE_PISCA,
+    'VERMELHO_PISCA': p.LED_VERMELHO_PISCA,
+    'AMBAR_PISCA': p.LED_AMBAR_PISCA,
+    'VERDE_PULSA': p.LED_VERDE_PULSA,
+    'VERMELHO_PULSA': p.LED_VERMELHO_PULSA,
+    'AMBAR_PULSA': p.LED_AMBAR_PULSA,
+}
+
+PORTAS_MOTOR = {'A': p.PORTA_A, 'B': p.PORTA_B, 'C': p.PORTA_C, 'D': p.PORTA_D}
+PORTAS_SENSOR = {1: 0, 2: 1, 3: 2, 4: 3}  # porta física -> índice interno (0-based)
+
+
+class RoboEV3:
+    def __init__(self, mac, canal=None, timeout=10):
+        self.conexao = ConexaoBluetooth(mac, canal=canal, timeout=timeout)
+
+    def fechar(self):
+        self.conexao.fechar()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.fechar()
+
+    # ---------- envio interno ----------
+
+    def _enviar(self, comando, com_resposta=False, bytes_globais=0):
+        contador = self.conexao.proximo_contador()
+        pacote = comando.montar(contador, com_resposta=com_resposta, bytes_globais=bytes_globais)
+        self.conexao.enviar(pacote)
+        if com_resposta:
+            dados = self.conexao.receber()
+            _, ok, payload = p.parse_resposta(dados)
+            if not ok:
+                raise RuntimeError("EV3 respondeu com erro pro comando")
+            return payload
+        return None
+
+    # ---------- Som / LED ----------
+
+    def apitar(self, frequencia=440, duracao_ms=500, volume=1):
+        cmd = p.Comando().add(
+            p.opSOUND, p.SOUND_TONE,
+            p.lc_auto(volume), p.lc_auto(frequencia), p.lc_auto(duracao_ms),
+        )
+        self._enviar(cmd)
+
+    def led(self, cor):
+        codigo = CODIGOS_LED.get(cor.upper())
+        if codigo is None:
+            raise ValueError(f"Cor de LED desconhecida: {cor}. Opções: {list(CODIGOS_LED)}")
+        cmd = p.Comando().add(p.opUI_WRITE, p.UI_WRITE_LED, p.lc0(codigo))
+        self._enviar(cmd)
+
+    # ---------- Espera por mudança (igual antes) ----------
+
+    @staticmethod
+    def espera_mudar(ler_valor, tempo_limite=15, intervalo=0.2, formatar=str, rotulo=""):
+        inicial = ler_valor()
+        print(f"  Valor inicial{f' ({rotulo})' if rotulo else ''}: {formatar(inicial)}")
+        inicio = time.time()
+        while time.time() - inicio < tempo_limite:
+            atual = ler_valor()
+            if atual != inicial:
+                print(f"  Mudou! {formatar(inicial)} -> {formatar(atual)}")
+                return True
+            time.sleep(intervalo)
+        print(f"  [TIMEOUT] Nenhuma mudança em {tempo_limite}s.")
+        return False
+
+    # ---------- Motores ----------
+
+    def girar_motor(self, porta, velocidade=30, duracao_ms=1000, frear=True):
+        """
+        Gira o motor por tempo (mais simples e robusto que graus/posição).
+        velocidade: -100 a 100 (negativo = sentido contrário)
+        """
+        bit_porta = PORTAS_MOTOR[porta]
+        acao = p.PARAR_BRAKE if frear else p.PARAR_COAST
+        cmd = p.Comando().add(
+            p.opOUTPUT_TIME_SPEED,
+            p.lc0(0),                    # layer 0
+            p.lc0(bit_porta),            # porta
+            p.lc1(velocidade),           # velocidade
+            p.lc0(0),                    # step1 (ramp-up) = 0
+            p.lc_auto(duracao_ms),       # step2 (duração em ms)
+            p.lc0(0),                    # step3 (ramp-down) = 0
+            p.lc0(acao),                 # ação ao parar
+        )
+        self._enviar(cmd)
+        time.sleep(duracao_ms / 1000 + 0.1)
+
+    def parar_motor(self, porta, frear=True):
+        bit_porta = PORTAS_MOTOR[porta]
+        acao = p.PARAR_BRAKE if frear else p.PARAR_COAST
+        cmd = p.Comando().add(p.opOUTPUT_STOP, p.lc0(0), p.lc0(bit_porta), p.lc0(acao))
+        self._enviar(cmd)
+
+    def testar_motor(self, porta, velocidade=30, duracao_ms=800):
+        print(f"Girando motor {porta} pra frente...")
+        self.girar_motor(porta, velocidade=velocidade, duracao_ms=duracao_ms)
+        time.sleep(0.2)
+        print(f"Girando motor {porta} pra trás...")
+        self.girar_motor(porta, velocidade=-velocidade, duracao_ms=duracao_ms)
+
+    def testar_motores(self):
+        print("========== TESTANDO MOTORES ==========\n")
+        for letra in PORTAS_MOTOR:
+            print(f"--- Motor na porta {letra} ---")
+            try:
+                self.testar_motor(letra)
+                print(f"Motor {letra} OK!\n")
+            except Exception as e:
+                print(f"[AVISO] Sem motor (ou erro) na porta {letra}: {e}\n")
+
+    # ---------- Sensores ----------
+
+    def _ler_sensor(self, indice_porta, modo, n_valores=1):
+        cmd = p.Comando().add(
+            p.opINPUT_DEVICE, p.INPUT_READY_SI,
+            p.lc0(0),                # layer 0
+            p.lc0(indice_porta),     # porta (0-3)
+            p.lc0(0),                # DO_NOT_CHANGE_TYPE
+            p.lc0(modo),             # modo
+            p.lc0(n_valores),        # quantidade de valores
+            p.gv0(0),                # onde guardar a resposta
+        )
+        payload = self._enviar(cmd, com_resposta=True, bytes_globais=4 * n_valores)
+        if n_valores == 1:
+            return struct.unpack_from('<f', payload, 0)[0]
+        return struct.unpack_from(f'<{n_valores}f', payload, 0)
+
+    def testar_ultrassonico(self, porta, tempo_limite=15):
+        indice = PORTAS_SENSOR[porta]
+        self.espera_mudar(
+            lambda: round(self._ler_sensor(indice, p.MODO_ULTRASSONICO_CM), 1),
+            tempo_limite=tempo_limite,
+            formatar=lambda v: f"{v} cm",
+        )
+
+    def testar_toque(self, porta, tempo_limite=15):
+        indice = PORTAS_SENSOR[porta]
+        self.espera_mudar(
+            lambda: self._ler_sensor(indice, p.MODO_TOQUE) > 0.5,
+            tempo_limite=tempo_limite,
+            formatar=lambda v: "pressionado" if v else "solto",
+        )
+
+    def testar_cor(self, porta, tempo_limite=15):
+        indice = PORTAS_SENSOR[porta]
+        self.espera_mudar(
+            lambda: int(round(self._ler_sensor(indice, p.MODO_COR_COR))),
+            tempo_limite=tempo_limite,
+            formatar=lambda v: CORES_SENSOR.get(v, f"desconhecida ({v})"),
+        )
+
+    def testar_sensores(self, tipos=('ultrassonico', 'toque', 'cor'), tempo_limite=15):
+        metodos = {
+            'ultrassonico': ('SENSORES ULTRASSÔNICOS', self.testar_ultrassonico),
+            'toque': ('SENSORES DE TOQUE', self.testar_toque),
+            'cor': ('SENSORES DE COR', self.testar_cor),
+        }
+        for tipo in tipos:
+            titulo, metodo = metodos[tipo]
+            print(f"========== TESTANDO {titulo} ==========\n")
+            for numero in PORTAS_SENSOR:
+                print(f"--- {tipo} na porta {numero} ---")
+                try:
+                    metodo(numero, tempo_limite=tempo_limite)
+                    print()
+                except Exception as e:
+                    print(f"[AVISO] Sem sensor (ou erro) na porta {numero}: {e}\n")
+
+    def testar_tudo(self, tempo_limite=15):
+        self.testar_motores()
+        self.testar_sensores(tempo_limite=tempo_limite)
+        print("Teste completo finalizado.")

jacarev3-0.1.0/src/jacarev3.egg-info/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: jacarev3
+Version: 0.1.0
+Summary: Lib em português pra controlar o LEGO EV3 via Bluetooth — protocolo Direct Commands implementado do zero, sem dependências externas
+Author: Ítalo Vinicius Barbosa Felix
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/i-barbosa/jacarEV3
+Project-URL: Repository, https://github.com/i-barbosa/jacarEV3
+Project-URL: Issues, https://github.com/i-barbosa/jacarEV3/issues
+Project-URL: Changelog, https://github.com/i-barbosa/jacarEV3/blob/main/CHANGELOG.md
+Keywords: ev3,lego,mindstorms,robotica,bluetooth,educacional
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Hardware
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jacarEV3 🐊
+
+Lib em português pra controlar o LEGO EV3 via Bluetooth. Sem dependências
+externas — só biblioteca padrão do Python.
+
+[![PyPI](https://img.shields.io/pypi/v/jacarev3)](https://pypi.org/project/jacarev3/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Instalação
+
+```bash
+pip install jacarev3
+```
+
+Ou pra desenvolver localmente:
+
+```bash
+git clone https://github.com/i-barbosa/jacarEV3.git
+cd jacarEV3
+pip install -e . --break-system-packages
+```
+
+## Uso rápido
+
+```python
+from jacarev3 import RoboEV3
+
+robo = RoboEV3('00:16:53:64:F8:B8')  # MAC do seu EV3
+
+robo.apitar()
+robo.led('VERDE')
+
+robo.testar_tudo()  # testa motores A-D e sensores 1-4
+
+robo.fechar()
+```
+
+Ou com `with` (fecha a conexão sozinho):
+
+```python
+with RoboEV3('00:16:53:64:F8:B8') as robo:
+    robo.apitar()
+    robo.testar_motores()
+```
+
+## Exemplos por funcionalidade
+
+### Som
+
+```python
+robo.apitar()                                  # bip padrão
+robo.apitar(frequencia=880, duracao_ms=300)    # agudo e curto
+robo.apitar(volume=5)                          # mais alto (1-100)
+```
+
+### LED
+
+```python
+robo.led('VERDE')
+robo.led('VERMELHO_PISCA')
+robo.led('DESLIGADO')
+```
+
+### Motor
+
+```python
+# Gira pra frente 1s, velocidade 30%
+robo.girar_motor('A', velocidade=30, duracao_ms=1000)
+
+# Gira pra trás (velocidade negativa)
+robo.girar_motor('A', velocidade=-30, duracao_ms=1000)
+
+# Solta o motor sem frear (roda livre)
+robo.parar_motor('A', frear=False)
+
+# Testa um motor específico
+robo.testar_motor('B')
+
+# Testa A, B, C, D de uma vez (pula os vazios com aviso)
+robo.testar_motores()
+```
+
+### Sensores
+
+```python
+# Cada teste espera o valor MUDAR de verdade antes de seguir
+# (aproxima algo do ultrassônico, aperta o toque, muda a cor)
+robo.testar_ultrassonico(porta=1)
+robo.testar_toque(porta=2)
+robo.testar_cor(porta=3)
+
+# Testa só alguns tipos, tempo de espera customizado
+robo.testar_sensores(tipos=('toque', 'cor'), tempo_limite=10)
+```
+
+## API completa
+
+### Som e LED
+| Método | Descrição |
+|---|---|
+| `apitar(frequencia=440, duracao_ms=500, volume=1)` | Toca um bip |
+| `led(cor)` | `VERDE`, `VERMELHO`, `AMBAR`, `DESLIGADO`, e variantes `_PISCA` / `_PULSA` |
+
+### Motores (portas A-D)
+| Método | Descrição |
+|---|---|
+| `girar_motor(porta, velocidade=30, duracao_ms=1000, frear=True)` | Velocidade de -100 a 100 |
+| `parar_motor(porta, frear=True)` | Para o motor |
+| `testar_motor(porta)` | Testa um motor específico |
+| `testar_motores()` | Testa A, B, C, D de uma vez |
+
+### Sensores (portas 1-4)
+| Método | Descrição |
+|---|---|
+| `testar_ultrassonico(porta, tempo_limite=15)` | Espera a distância mudar |
+| `testar_toque(porta, tempo_limite=15)` | Espera pressionado/solto |
+| `testar_cor(porta, tempo_limite=15)` | Espera a cor mudar |
+| `testar_sensores(tipos=(...), tempo_limite=15)` | Testa os 3 tipos nas 4 portas |
+| `testar_tudo(tempo_limite=15)` | Motores + todos os sensores |
+
+## Troubleshooting
+
+**`OSError` / timeout ao conectar**
+Confirma que o EV3 tá pareado nas Configurações Bluetooth do Windows/Linux
+e que o Bluetooth dele tá visível/ligado antes de rodar o script.
+
+**`[AVISO] Sem motor (ou erro) na porta X`**
+Normal se não tiver motor físico conectado nessa porta — o método pula e
+segue pros outros.
+
+**`speed must be in range [1-100]`**
+Velocidade tem que ser um valor entre -100 e 100 (direção pelo sinal, não
+por valores fora do range).
+
+**`EV3 respondeu com erro pro comando`**
+Geralmente é modo/porta errada no sensor (ex: pedir leitura de cor num
+sensor de toque). Confere se o sensor físico bate com o tipo do método
+chamado.
+
+## Status
+
+v0.1.0 — protocolo validado byte a byte contra a documentação oficial da
+LEGO (Communication Developer Kit), ainda em bateria de testes no robô
+físico. Veja [CHANGELOG.md](CHANGELOG.md) pro histórico de versões.
+
+## Contribuindo
+
+Issues e PRs são bem-vindos em
+[github.com/i-barbosa/jacarEV3](https://github.com/i-barbosa/jacarEV3).
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

jacarev3-0.1.0/src/jacarev3.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/jacarev3/__init__.py
+src/jacarev3/conexao.py
+src/jacarev3/protocolo.py
+src/jacarev3/robo.py
+src/jacarev3.egg-info/PKG-INFO
+src/jacarev3.egg-info/SOURCES.txt
+src/jacarev3.egg-info/dependency_links.txt
+src/jacarev3.egg-info/top_level.txt

jacarev3-0.1.0/src/jacarev3.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jacarev3-0.1.0/src/jacarev3.egg-info/top_level.txt

@@ -0,0 +1 @@
+jacarev3