Module documentation

vbit2-interface documentation

class vbit2interface.interface.Client(host, port)

VBIT2 interface client

• Parameters:
  • host – Hostname of server.
  • port – Port number of server.

clearHeaderTemplate(magazine)

Clear magazine specific VBIT2 header template.

• Parameters: magazine – magazine number in range 1 to 8.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • ValueError – Invalid magazine number.
  • VersionError – Server version is too old for this command.

close()

Close network connection and clear state.

closePage()

Close currently open page.

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, or invalid channel.
  • VersionError – Server version is too old for this command.

connect()

Attempt to connect to VBIT2 control interface server and interrogate API version.

• Raises: VersionError – The server reports a future major version.

datacastFormatA(data, IAL=0, SPA=0, CI=0, RI=None, explicitCI=False, useDL=False, retries=None)

Create Format A data broadcast packet and insert into transmission buffer.

Automatically retries command if server reports buffer is full.

• Returns: Number of bytes successfully transmitted.
• Parameters:
  • data – bytes or bytearray containing payload.
  • IAL – Interpretation and Address Length.
  • SPA – Service Packet Address.
  • CI – Continuity Indicator.
  • RI – Repeat Indicator.
  • explicitCI – flag to enable an explicit continuity indicator byte.
  • useDL – flag to enable a Data Length byte.
  • retries – optionally override the number of attempts.
• Raises:
  • ConnectionError – No connection to server.
  • ResourceBusyError – Data broadcast buffer is full.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid IAL argument.
  • VersionError – Server version is too old for this command.

datacastFormatB(AN, AI, data, retries=None)

Inject 490 byte Format B data broadcast bundle into buffer.

Automatically retries command if server reports buffer is full.

• Parameters:
  • data – bytes or bytearray containing payload.
  • AN – Databroadcast Application Number.
  • AI – Databroadcast Application Identifier.
  • retries – optionally override the number of attempts.
• Raises:
  • ConnectionError – No connection to server.
  • ResourceBusyError – Data broadcast buffer is full.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid AN or AI argument, or data bundle incorrect length.
  • VersionError – Server version is too old for this command.

datacastRaw(data, retries=None)

Inject 40 bytes of pre-encoded data into data broadcast buffer.

Automatically retries command if server reports buffer is full.

• Parameters:
  • data – bytes or bytearray containing exactly 40 bytes.
  • retries – optionally override the number of attempts.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid data length.
  • VersionError – Server version is too old for this command.

deleteMagEnhancement(magazine, designationCode=None)

Delete magazine enhancement packet(s).

• Parameters:
  • magazine – magazine number in range 1 to 8.
  • designationCode – optional packet designation code in range 0 to 15.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • ValueError – Invalid magazine number or designation code.
  • VersionError – Server version is too old for this command.

deletePage(number)

Delete a page from the teletext service.

• Parameters: number – hexadecimal page number.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, or invalid channel.
  • ValueError – Invalid page number.
  • VersionError – Server version is too old for this command.

deleteRow(number, designationCode=None)

Delete row(s) from selected sub-page.

If no designation code is specified for rows greater than 25, all packets with that row number are removed.

• Parameters:
  • number – row number in range 1 to 28
  • designationCode – optional packet designation code in range 0 to 15 for rows > 25
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no sub-page selected.
  • ValueError – Invalid row number or designation code.
  • VersionError – Server version is too old for this command.

deleteSubPage(subcode)

Delete sub-page in open page.

• Returns: Number of sub pages in page.
• Parameters: subcode – hexadecimal sub-code number.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no page open.
  • ValueError – Invalid subcode.
  • VersionError – Server version is too old for this command.

getBSDPReserved()

Read reserved bytes of Broadcast Service Data Packet.

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • VersionError – Server version is too old for this command.

getBSDPStatus()

Read Broadcast Service Data Packet status display message.

• Returns: 20 bytes of character data.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • VersionError – Server version is too old for this command.

getFastext()

Read navigation packet data of the selected sub-page.

• Returns: named tuple containing list of page numbers and list of sub-codes.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, no sub-page selected, or row does not exist.
  • VersionError – Server version is too old for this command.

getHeaderTemplate(magazine=None)

Read VBIT2 header template.

• Returns: 32 bytes of character data.
• Parameters: magazine – optional magazine number in range 1 to 8 to read magazine specific template.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no header template set.
  • ValueError – Invalid magazine number.
  • VersionError – Server version is too old for this command.

getMagEnhancement(magazine, designationCode)

Read magazine enhancement packet.

• Returns: 40 bytes of packet data using VBIT2 triplet encoding.
• Parameters:
  • magazine – magazine number in range 1 to 8.
  • designationCode – packet designation code in range 0 to 15.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or packet does not exist.
  • ValueError – Invalid magazine number or designation code.
  • VersionError – Server version is too old for this command.

getPageFunctionCoding()

Read function and coding variables of open page

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no page open.
  • VersionError – Server version is too old for this command.

getRow(number, designationCode=None)

Read row data for row in selected sub-page.

• Returns: 40 bytes of packet data in relevant VBIT2 row encoding.
• Parameters:
  • number – row number in range 1 to 28.
  • designationCode – packet designation code in range 0 to 15 for rows > 25.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, no sub-page selected, or row does not exist.
  • ValueError – Invalid row number or designation code.
  • VersionError – Server version is too old for this command.

getRowAdaptive()

Read state of Row Adaptive transmission mode flag.

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • VersionError – Server version is too old for this command.

getSubPageOptions()

Read control flags and cycle timings for selected sub-page.

• Returns: named tuple containing current page options.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no sub-page selected.
  • VersionError – Server version is too old for this command.

getVersion()

Interrogate API version of server.

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error.
  • VersionError – The server reports a future major version.

openPage(number, oneShot=False, retries=None, interval=None)

Open/create page in teletext service.

• Parameters:
  • number – hexadecimal page number.
  • oneShot – flag to set page to one shot transmission.
  • retries – optionally override the number of attempts.
  • interval – optionally override retry interval.
• Raises:
  • ConnectionError – No connection to server.
  • ResourceBusyError – Page is currently locked.
  • RuntimeError – Server returned an unexpected error, or invalid channel.
  • TypeError – Invalid oneShot flag.
  • ValueError – Invalid page number.
  • VersionError – Server version is too old for this command.

setBSDPReserved(data)

Set reserved bytes of Broadcast Service Data Packet.

• Parameters: data – bytes or bytearray containing exactly 4 bytes.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid data length.
  • VersionError – Server version is too old for this command.

setBSDPStatus(data)

Set Broadcast Service Data Packet status display message.

• Parameters: data – bytes or bytearray containing exactly 20 bytes.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid data length
  • VersionError – Server version is too old for this command.

setChannel(channel)

Select interface channel number on server.

• Parameters: channel – channel number from 0 to 15.
• Raises:
  • ConnectionError – No connection to server.
  • ResourceBusyError – Channel is already in use.
  • RuntimeError – Server returned an unexpected error.
  • ValueError – Invalid channel argument.
  • VersionError – Server version is too old for this command.

setFastext(pages, subcodes=None)

Set navigation packet data for the selected sub-page.

• Parameters:
  • pages – list of exactly six hexadecimal page numbers.
  • subcodes – optional list of exactly six hexadecimal page sub-codes.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no sub-page selected.
  • TypeError – Invalid pages or subcodes.
  • ValueError – Invalid page number or sub-code.
  • VersionError – Server version is too old for this command.

setHeaderTemplate(data, magazine=None)

Set VBIT2 header template.

• Parameters:
  • data – bytes or bytearray containing exactly 32 bytes.
  • magazine – optional magazine number in range 1 to 8 to set template for a single magazine.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid data length or magazine number.
  • VersionError – Server version is too old for this command.

setMagEnhancement(magazine, data)

Set magazine enhancement packet.

• Parameters:
  • magazine – magazine number in range 1 to 8.
  • data – bytes or bytearray containing exactly 40 bytes using VBIT2 triplet encoding.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid data type.
  • ValueError – Invalid magazine number or data length.
  • VersionError – Server version is too old for this command.

setPageFunctionCoding(function, coding)

Set function and coding variables of open page.

• Parameters:
  • function – page function number from 0 to 11.
  • coding – page coding number from 0 to 5.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no page open.
  • ValueError – Invalid page function or coding.
  • VersionError – Server version is too old for this command.

setRow(number, data)

Write row data to row in selected sub-page.

• Parameters:
  • number – row number in range 1 to 28.
  • data – bytes or bytearray containing exactly 40 bytes using appropriate VBIT2 row encoding.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no sub-page selected.
  • TypeError – Invalid data type.
  • ValueError – Invalid row number or data length.
  • VersionError – Server version is too old for this command.

setRowAdaptive(flag)

Set state of Row Adaptive transmission mode flag.

• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error or invalid channel.
  • TypeError – Invalid flag.
  • VersionError – Server version is too old for this command.

setSubPage(subcode)

Select/create sub-page in open page.

• Returns: Number of sub pages in page.
• Parameters: subcode – hexadecimal sub-code number.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no page open.
  • ValueError – Invalid subcode.
  • VersionError – Server version is too old for this command.

setSubPageOptions(erase=None, newsflash=None, subtitle=None, suppressHeader=None, update=None, interruptedSequence=None, inhibit=None, transmitPage=None, language=None, region=None, cycleTime=None, timedMode=None)

Set control flags and cycle timings for selected sub-page.

All arguments are optional. If any are undefined the current state of those values is read from the server.

• Returns: Named tuple containing new page options.
• Parameters:
  • erase – C4 Page Erase flag.
  • newsflash – C5 Newsflash flag.
  • subtitle – C6 Subtitle flag.
  • suppressHeader – C7 Suppress Header flag.
  • update – C8 Update Indicator flag.
  • interruptedSequence – C9 Interrupted Sequence flag.
  • inhibit – C10 Inhibit Display flag.
  • transmitPage – subpage on air flag.
  • language – C12-14 national option character subset value.
  • region – character set region.
  • cycleTime – carousel cycle time in magazine cycles or seconds.
  • timedMode – flag indicating cycle time represents seconds.
• Raises:
  • ConnectionError – No connection to server.
  • RuntimeError – Server returned an unexpected error, invalid channel, or no sub-page selected.
  • ValueError – Invalid language or region.
  • VersionError – Server version is too old for this command.

exception vbit2interface.interface.ResourceBusyError(msg)

Interface server temporarily unable to complete command.

exception vbit2interface.interface.VersionError(msg)

Command not compatible with version number reported by server.