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.

Portal flow (handshake → profile)¶

The box (or emulator) drives the portal in a fixed sequence; understanding it makes the checklist steps 4-5 concrete:

handshake — GET portal.php?type=stb&action=handshake&mac=…&prehash=… → the server returns a token. prehash is a client-computed handshake hash (derived by the box/emulator from its identity + the MAC); you do not set it in the URL — the client generates it per request.
get_profile — GET portal.php?type=stb&action=get_profile with Authorization: Bearer <token> and the device identifiers (mac, sn, stb_type, device_id…). The server validates the device (MAC row, lock_device fields, allowed_stb_types) and returns the profile, whose status says whether the box is authorized.
Subsequent calls (channel list, EPG, create_link) reuse the same Bearer token.

Server side, PortalHandler.php orchestrates handshake/get_profile and portal.php runs the device checks. (In some builds the box first hits /server/load.php for a load-balancer handshake before the portal calls — that is normal.)

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.

/ACCESS_CODE/ is the panel's per-install access-code path (the code from the panel URL); /c/ is a short alias that nginx rewrites to the same portal handler. Either works — use whichever your nginx/emulator setup expects; they reach the same portal.php.

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:

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¶

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:

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

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

http://192.168.110.251/HgBjUjSI/

What `your device is not active` Means¶

The profile status field reports the outcome: status = 0 — device authorized/active (normal); status = 1 — device failed authentication/verification, which surfaces as your device is not active. (Only 0/1 are used for this gate.)

Common causes:

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

Quick Checklist¶

Open portal with a correct prefix (/ACCESS_CODE/ or /c/).
In STB Emulator, do not use URL with action=handshake as portal URL.
Pass all required fields (mac, sn, stb_type, device_id, device_id2, hw_version).
Verify handshake returns token and the next get_profile sends Authorization Bearer.
If Authorization does not reach PHP, temporarily enable auth_via_query=1.
If STB type restrictions apply, add debug_key=1.
If issue persists, verify the device in the admin panel: MAG Devices page (the mag_devices row, MAC + lock_device toggle) and the Ministra settings' allowed STB types list (allowed_stb_types).

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/Ministra/PortalHandler.php

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