# Ministra: Browser STB Emulation

Quick reference for running Ministra in a regular browser (without a real MAG set-top box) and diagnosing the `your device is not active` error.

---

## When To Use

- You need to verify `index.html` loading and `portal.php` calls via token path.
- You need to quickly debug handshake/get_profile in a browser.
- You need to understand why a device gets inactive status.

---

## Supported URLs

Usually two variants are used (depending on nginx config):

- `http://HOST/ACCESS_CODE/`
- `http://HOST/c/`

For browser emulation it is important that `index.html` opens, and API steps go to `portal.php` inside the same prefix.

For STB Emulator, the entry point must also be the base prefix (or `portal.php` without query parameters), not a prebuilt `action=handshake` request.

---

## Black Screen In STB Emulator

If the emulator is configured with a URL like:

```text
http://HOST/ACCESS_CODE/portal.php?type=stb&action=handshake&mac=...&token=&prehash=...&JsHttpRequest=1-xml
```

this is a configuration error. Such URL returns handshake JSON and is not a portal screen, so the emulator usually shows a black screen.

Use one of these options:

- `http://HOST/ACCESS_CODE/`
- `http://HOST/c/`
- `http://HOST/ACCESS_CODE/portal.php` (only if the emulator requires a direct `portal.php` path, but without `type/action/token/prehash` in URL)

Parameters `type`, `action`, `JsHttpRequest`, `token`, and `prehash` must be generated by the client (emulator) itself at each API step.

---

## Required GET Parameters

If device checks are enabled, pass identifiers explicitly:

| Parameter | Purpose |
| --- | --- |
| `mac` | Device MAC for handshake |
| `sn` | Device serial number |
| `stb_type` | STB model (for example `MAG250`) |
| `device_id` | First device id |
| `device_id2` | Second device id |
| `hw_version` | Hardware version |

Without these values, the server may reject `get_profile` as an invalid device.

---

## Useful GET Parameters

| Parameter | When It Is Needed |
| --- | --- |
| `debug_key` | Bypass `allowed_stb_types` restriction on the client side |
| `ver` | If image/version lock is enabled |
| `image_version` | If image version comparison is enabled |
| `access_token` | To test re-login with a prebuilt token |
| `auth_via_query` | Debug mode: duplicate token in query if Authorization header is stripped by proxy/nginx |
| `debug` | Client debug mode (enabled by default in the current build) |

---

## Example URL

```text
http://192.168.110.251/HgBjUjSI/?mac=00:1A:79:11:22:33&sn=062014N000001&stb_type=MAG250&device_id=ABC123&device_id2=DEF456&hw_version=1.7-BD-00&debug_key=1
```

If needed, add:

```text
&ver=ImageDescription%3Aemu&image_version=218&auth_via_query=1
```

For STB Emulator profile settings, specify only the portal URL, for example:

```text
http://192.168.110.251/HgBjUjSI/
```

---

## What `your device is not active` Means

The message appears when profile response contains `status = 1` (device failed authentication/verification).

Common causes:

1. MAC is not found in `mag_devices`.
2. `sn`, `device_id`, `device_id2`, `hw_version` do not match when `lock_device = 1`.
3. STB model does not pass `allowed_stb_types` whitelist.
4. Handshake token is invalid or rejected on `get_profile`.

---

## Quick Checklist

1. Open portal with a correct prefix (`/ACCESS_CODE/` or `/c/`).
2. In STB Emulator, do not use URL with `action=handshake` as portal URL.
3. Pass all required fields (`mac`, `sn`, `stb_type`, `device_id`, `device_id2`, `hw_version`).
4. Verify handshake returns token and the next `get_profile` sends Authorization Bearer.
5. If Authorization does not reach PHP, temporarily enable `auth_via_query=1`.
6. If STB type restrictions apply, add `debug_key=1`.
7. If issue persists, verify device row in DB (`mag_devices`) and `lock_device` flag.

---

## Implementation References

- Client parameters and API calls: `src/ministra/xpcom.common.js`
- Debug/get parameter initialization: `src/ministra/index.html`
- Server-side device checks and profile: `src/ministra/portal.php`
- Handshake/get_profile orchestration: `src/Modules/ministra/PortalHandler.php`

## Related files

| File | Role |
| --- | --- |
| `src/ministra/portal.php` | Ministra portal entry point |
| `src/ministra/index.html` | Emulated STB browser page |
| `src/Modules/ministra/PortalHandler.php` | Portal request handler |
