BlueStacks ADB: conectar e configurar a porta no MAS

Este guia mostra como conectar o BlueStacks ao Macro Automation Studio (MAS) pelo ADB: ativar o BlueStacks ADB, encontrar a porta ADB e adicionar a instância como dispositivo. Ele cobre o BlueStacks 5 no Windows e a build do BlueStacks para Macs com Apple Silicon, e termina com os erros que as pessoas mais encontram.

Antes de começar

• MAS instalado e com login feito no Windows 10 ou 11, ou em um Mac com Apple Silicon. O MAS é um download gratuito para o teste; pegue-o na página de download.
• BlueStacks instalado a partir de bluestacks.com e aberto pelo menos uma vez.
• A instância totalmente iniciada até a tela inicial do Android.
• Os apps que você quer automatizar instalados e com login feito dentro do BlueStacks.

1. Instalar o BlueStacks

2. Configurações recomendadas

O MAS compara imagens template pixel a pixel, então a tela não pode mudar depois que você captura os templates. Abra Configurações pelo ícone de engrenagem na barra lateral e defina:

Clique em Salvar alterações e reinicie a instância quando o BlueStacks pedir. Macros escritas contra a base do MAS esperam 540x960 a 240 DPI; uma macro que você mesmo escreve espera a resolução que você capturou no Asset Lab. Se a execução ficar travando, feche apps em segundo plano e dê mais núcleos e memória à instância.

3. Ativar o ADB no BlueStacks 5

O BlueStacks vem com o ADB desligado. O MAS precisa dele ligado.

4. A porta ADB do BlueStacks e como o MAS a escaneia

O MAS não roda adb devices para descobrir emuladores. Ele escaneia os processos em execução e mantém uma porta quando todas estas condições valem:

• O nome do processo contém hd-player ou bluestacks.
• A porta está entre 5555 e 8500.
• O socket escuta em 127.0.0.1, 0.0.0.0 ou em todas as interfaces.

As portas que batem aparecem na caixa de diálogo Adicionar novo dispositivo com o rótulo Bluestacks, por exemplo 5555 - Bluestacks. O MAS escaneia quando você abre um grupo de dispositivos e a cada clique em Atualizar. Cada instância do BlueStacks escuta na própria porta, então duas instâncias dão duas entradas.

5. Conectar o BlueStacks pelo ADB no MAS

1. Abra Grupos de dispositivos na barra lateral e abra um grupo, ou crie um.
2. Clique em Adicionar dispositivo.
3. Digite um Nome do dispositivo com até 50 caracteres.
4. Em Porta, escolha a entrada Bluestacks desta instância. Clique em Atualizar se a lista estiver vazia.
5. Se o BlueStacks mostrar uma porta que o MAS não listou, escolha Porta personalizada e digite-a. O MAS aceita de 1024 a 65535.
6. Se quiser, escolha uma Macro inicial.
7. Clique em Adicionar dispositivo e depois em Iniciar no card do dispositivo.

O card mostra Conectando e depois Em execução. O MAS inicia seu próprio servidor adb, remove qualquer entrada antiga de 127.0.0.1:<port> e roda adb connect contra ela.

Macros no BlueStacks

O gravador de macros do próprio BlueStacks repete toques em coordenadas fixas. Uma macro do MAS é um script Python que olha para a tela antes: o template matching encontra o botão, o OCR lê o texto e as tentativas repetidas absorvem um carregamento lento ou um pop-up. Primeiros passos roda sua primeira macro, Macros com reconhecimento de imagem reconstrói uma rotina gravada como uma rotina que enxerga a tela, e o Agendador a roda diária, semanal ou mensalmente.

Várias instâncias do BlueStacks

As instâncias criadas no Gerenciador de multi-instâncias escutam cada uma na própria porta ADB. Adicione cada uma como um dispositivo separado no mesmo grupo de dispositivos, dê a cada uma sua macro e seu perfil de configurações, e use Iniciar todos e Parar todos no grupo. Veja Grupos de dispositivos para argumentos e proxies por dispositivo.

Solução de problemas

Ativar o ADB no BlueStacks 5

A lista Porta no MAS está vazia e adb connect 127.0.0.1:5555 responde “cannot connect” ou “connection refused”. O ADB está desligado. Abra Configurações, clique em Avançado, ative Android Debug Bridge, clique em Salvar alterações, reinicie a instância e clique em Atualizar em Adicionar novo dispositivo. Se a aba Avançado não tiver esse botão, instale o BlueStacks 5 atual pelo site do fabricante.

Encontrar ou mudar a porta ADB

A porta fica abaixo do botão Android Debug Bridge como 127.0.0.1:<port>. O BlueStacks a atribui na inicialização e muda para outra porta quando 5555 está ocupada, então ela pode mudar depois que você cria, clona ou exclui instâncias; o guia de ADB do fabricante não documenta nenhum campo para defini-la à mão. Quando ela mudar, clique em Editar dispositivo no card do MAS e escolha a porta nova. Abrir as instâncias sempre na mesma ordem mantém as portas estáveis.

ADB device not found

O card termina em Erro com “Failed to start device”, o log diz “unable to connect to device”, ou um script lança DeviceNotConnectedError.

• A instância ainda está iniciando. Aguarde a tela inicial e clique em Iniciar de novo.
• A porta no card não é a porta que o BlueStacks mostra. Corrija com Editar dispositivo.
• Uma atualização desligou o ADB de novo. Confira a aba Avançado.
• Rode adb connect 127.0.0.1:<port> em um terminal. “connected to” significa que o MAS também vai conectar.

O dispositivo aparece como offline

adb devices lista 127.0.0.1:<port> offline e os comandos travam. O daemon adb dentro da instância parou de responder, em geral depois de uma suspensão, uma atualização ou um segundo servidor adb na máquina. Clique em Parar no card, reinicie a instância, feche outras ferramentas que rodam o próprio servidor adb e clique em Iniciar; o MAS reconecta do zero. Se continuar offline, reinicie o MAS para que o servidor adb dele inicie limpo. Mais correções em Solução de problemas de ADB.

BlueStacks ADB no Mac

Duas coisas são diferentes no Mac. Primeiro, o MAS precisa de um binário do adb: ele procura dentro do pacote do app, depois no seu PATH e depois nas pastas do Homebrew. Se o MAS informar “ADB executable not found. Please install ADB using your package manager”, instale o adb com o Homebrew e reinicie o MAS:

brew install android-platform-tools

Segundo, o MAS sempre disca 127.0.0.1, então o BlueStacks precisa rodar no mesmo Mac e expor o ADB. O BlueStacks Air é a única build para Apple Silicon e suas configurações documentadas não têm botão de ADB; sem ele, o MAS não consegue controlá-lo.

Controle pelo Python

Com o card em Em execução, o src/app.py de uma macro controla o BlueStacks pelo pacote mas. O MAS escolhe a porta, então os scripts nunca a referenciam.

import mas

size = mas.get_screen_size()
mas.log(f"BlueStacks screen is {size.width}x{size.height}")

match = mas.find_object_retry(1234, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y)

Leia a visão geral do SDK para todos os namespaces, e Controlar um emulador Android pelo Python para um primeiro script completo.