Polycom Microbrowser

Most of the Polycom have a feature called Microbrowser - "a fully compliant HTTP/1.1 user agent" says Polycom docs - that allows browsing of simple XHTML web pages on the phone's LCD screen. In addition, the microbrowser can also be used to display information on the phone's idle screen; however, in this mode navigation is not possible. A third mode of operation is by pushing XML to the phone.

There is extremely detailed information about this feature in the Polycom documentation. Check out the Web Application Developer's guides, available in PDF at http://support.polycom.com/PolycomService/support/us/support/voice/soundpoint_ip/soundpoint_ip550.html

To use this feature, you set a starting URL in the configuration file that gets loaded when the phone boots, or you can set it using the phone's web configuration page. The option is called: Main Browser Home.

Hit the Services or Applications hard button key on the phone to acces this URL.

The idle display can also be configured to access a URL, and automatically refresh on a periodic basis. The provisioning variables are mb.idleDisplay.home="(url)" and mb.idleDisplay.refresh="(seconds"). In addition, the microbrowser respects traditional refresh headers.

The following tags are the only tags known to be supported. Unknown (but properly formatted) tags are ignored by the microbrowser, tags should be lowercase

DOCTYPE, html, head, title, body, img, b, u, a, br, hr, img, form, input, table/caption/th/tr/td/thead/tbody/tfoot

David Gomillion dgomillion at eyecarenow.com posted on the Asterisk Users Mailing List his experiences implementing a timeclock system using the Polycom Microbrowser.

Here are David's hints for using the Microbrowser

All HTML tags including single element tags must be closed as the browser is very strict on XHTML syntax.

The BR tag for instance should be written as <BR/>, <BR /> or even could be <BR></BR> but <BR> by itself is not valid in XHTML.

XHTML Syntax errors will cause the browser to return an error. No portion of the page will be rendered.

This will not work:
<input type="text" name="myfield">
This will
<input type="text" name="myfield" />

This will not work:
This will:

Tags which are specifically not supported

The following are not supported:
  • <b>...</b>
  • <i>...</i>
  • <small>...</small>
  • <select>...</select>
  • <table>...</table> (And associated element tags)

Note: The SIP 2.2 firmware now supports a much wider selection of XHTML tags, including <table>, <select> and many others. Polycom has also published the Web Application Developer's Guide for the SoundPoint IP/SoundStation IP Family (pdf/36 pages) detailing what tags and attributes are supported in SIP 2.2.0.

The above link is gone but a new Web Developer's Guide was released in August 2008 for SIP 3.1, adding support for tables, programmable soft keys, internal URLs, Phone Events and Phone State.

Image support

  • Inline images are supported by the microbrowser. Only 1bpp and 4bpp windows byte order .bmp's seem to be supported. .GIF, .JPG, .PNG and other common web image formats do not work. Make sure to close the IMG tag (ex: <img src="image.bmp" height="20" width="40"/>)
  • If you don't include image dimensions in the IMG tag, the page will render but will take a much longer time to draw as it has to reformat the layout both before and after it loads EACH IMAGE on the page!
  • If you specify a width other than the width and height of the image it will be scaled to the dimensions you specify using a crude nearest neighbor algorithm. This is useful for drawing <hr> equivalents with a 1x1 pixel black bmp or aligning text with a 1x1 pixel white .bmp (which is invisible on the screen.)

Special character and international character support

  • Special characters used in HTML with a character code, &quot; for instance, are not supported by the microbrowser. For the purposes of it being a very strict XHTML parser, I suppose it throws the proper "Entity Not Defined" error, but using correct DTD's doesn't seem to make it work either. You should either avoid special characters entirely or simply use them in binary form and see if the phone will tolerate it. Further documentation would be required from Polycom in order to know for sure why this is the case.


  • Page titles are prominently displayed, so choose your titles appropiately.
  • Session management should be tested carefully, otherwise hitting the back key on the phone may re-submit old data.
  • It is possible to simulate tables or align text or images to columns in the microbrowser through the use of the old HTML trick of using invisible images to pad whitespace. However since the browser uses a proportional font you have to know the widths of each character in order to do accurately pad text. The width of each character in the microbrowser's font is provided here along with a short description of how to use the technique: Polycom Microbrowser Character Widths

Another person's experiences

anishp anishp is is at at win-ent dot dot com com
  • the polycom does not respect the maxlength or size variables for an input box
  • improper pages will cause the phone to reboot or lockup
  • input type of checkbox does not render
  • ! in text fields will apparently cause the phone to reboot on random.
  • <select name="stuff[]" multiple> does not work
  • nor does a drop down select
  • radio buttons do work, but when used in conjuction with PHP, some pretty funky stuff happens

cmaj found many of these bugs were fixed, making programming easier. Point your phone's microbrowser to: http://www.penguinpbx.com/phoneapps/polycom/index.html

Sample Scripts

Newer Firmware Fixes and Gotchas (3.1.1)

  • 35087: Changed boot-up behaviour so that idle browser only starts about 2 minutes after the phone has booted up (this is to optimize memory use)
  • 7444: Added table support to microbrowser
  • 19443: Added microbrowser support for forms within tables
  • mb.idleDisplay.home can be empty or any fully formed valid HTTP URL. Length up to 255 characters.

Pushing XML

cmaj got curl to drive the phone using firmware 3.2.3 with some help to find the "/push" part from the perl script test_alert2.pl off this thread: http://groups.google.com/group/VOIP-Users-Conference/browse_thread/thread/e15af3d57331f699
First, cribbing from the Polycom docs, in server.cfg or mac.cfg or however you config the phone - heck even the web interface under "Applications" tab - setting these as so:
  • apps.push.messageType=3
  • apps.push.username=bob
  • apps.push.password=1234
Then, instead of firing up perl, you can finagle curl:
  • curl -d "<PolycomIPPhone><Data priority=\"critical\"><h1>Howdy World</h1></Data></PolycomIPPhone>" -H "Content-Type: application/x-com-polycom-spipx" -u bob:1234 --digest http://ip.of.the.phone/push
And that should spit out "Push Message will be displayed successfully" if you did it right. (Or you could just look at the phone and listen for the chirp it makes when displaying the text.)
Messages of "critical" priority will appear immediately on the screen regardless of call state. Use "normal" priority to wait until the phone is idle (perhaps good for an after-call display.)
You probably can't use the Asterisk CURL() / CURLOPT() functions as they lack digest authentication support. Try System() instead. Here's an example AEL2 macro working in Asterisk 1.8:

macro polly-pusher(ip_, userpass_, priority_, msg_) {
    if( "${ip_}" == "" ) {
        ip_ = "${CHANNEL(peerip)}";
    if( "${userpass_}" == "") {
        userpass_ = "bob:1234";
    if( "${priority_}" != "normal" ) {
        priority_ = "critical";
    xml = "<PolycomIPPhone><Data priority='${priority_}'>${msg_}</Data></PolycomIPPhone>";
    url = "http://${ip_}/push";
    extrahead = "Content-Type: application/x-com-polycom-spipx";
    TrySystem(curl -d "${xml}" -u "${userpass_}" --digest -H "${extrahead}" ${url});

To send a msg to the phone you are calling in with, try:

&polly-pusher(,,,"Howdy World");

Polycom docs say you can push up to 1KB this way. You can also push URLs. Be aware it is all over HTTP, so not too secure, but the phone's internal browser only serves up HTTP. Pushing an URL to the phone to grab HTTPS off another server might be more secure - but slower.

Although specific technical information is not published by polycom, as a sidenote, the microbrowser running on the SoundPoint IP 650 renders pages much more quickly than on the 600/601, most likely due to the phone containing a more powerful CPU. Same with the 550/560 vs. 501s - the former is much faster.

See Also

Created by: admin, Last modification: Sat 12 of Feb, 2011 (19:10 UTC) by cmaj
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+