Author Archives: Kevin

V2X Python Wrapper Updated for Python 3

We’ve updated the Python wrapper in our V2X API packages to support Python 3 (in addition to supporting Python 2.7).   Also, all platforms, not just 64-bit ones, now include the Python wrapper.

About Objective System’s V2X API

The V2X API is available for C++, Java, and C#.  It supports encoding/decoding V2X messages defined by SAE J2735 and ETSI standards.

The Python wrapper enables easy conversion between binary and text encodings by providing a simple Python interface on top of the C++ API.

For more, go here.

V2X API Library Update

With the recent release of ASN1C 7.3.3, we’ve also updated our V2X API library.  We’ve added support for ETSI TS 103 301 SPATEM, MAPEM, IVIM, SREM, and SSEM messages.

Our V2X API library provides support for encoding V2X (Vehicle-to-everything) messages.  The library is available for C++ (as a shared library) Java (JAR), and C# (DLL).   A simple Python wrapper for the C++ shared library is also provided.

Users of previous versions of the Java or C# library should be aware that a slight change was made: classes in the v2x package/namespace have been split into one of two sub-package/namespaces: v2x.j2735 or v2x.etsi.

Users of previous versions of the C++ or Python library should be aware that the shared library has been split into two files (*_j2735 and *_etsi).  Python users must have both libraries present as the Python wrapper library requires both of them.  C++ users can use whichever one is appropriate.

Extending JSON Encoding Rules (JER)

ITU-T standardized the JSON encoding of ASN.1 data in X.697 (JER), but we believe customers want to support use cases the standard doesn’t address.  This post briefly describes two extensions to JER that we’re planning to implement in our ASN.1 compiler, ASN1C.  We plan to implement the first extension (for contents constraints) as an undocumented feature in a 7.3.x patch release in the September-October time frame.

Extension for Contents Constraints

The first extension relates to encoding of BIT STRING or OCTET STRING with a contents constraint.  For example:

OCTET STRING (CONTAINING SomeType)

In short, the purpose of this first extension is to allow the contained type to be encoded in JSON just as it would be encoded if it weren’t a contained type, instead of encoding it as a string of hexadecimal characters.  This extension is all about making the JSON more human-readable.  Here’s an example:

Say your ASN.1 has something like this:

   my-bit-string BIT STRING ( CONTAINING TwoStrings )
…

TwoStrings ::= SEQUENCE {
   one UTF8String,
   two UTF8String
}

The standard JER encoding would look something like:

"my-bit-string" : { "value" : "7B20226F6E6522203A20226D6F6E6579222C202274776F22203A202273686F7722207D", "length" : 280 }

Our extension would instead produce something like:

"my-bit-string" : { "value+" : { "one" : "money", "two" : "show" } }

Extension for Values of Unknown Types

The second extension relates to encoding values of unknown types, which may appear as SEQUENCE/SET/CHOICE extension elements or in open types.  It isn’t possible to convert values of unknown types from BER or PER to standard JER.  Since its type isn’t known, the value is stuck in BER or PER, so to speak.  So, in short, the purpose of our second extension is to enable converting the rest of your data to JSON while preserving what can’t be properly converted (in case you need it) and making a round trip back to the original encoding possible.  This is done by embedding the original encoding in the JSON in hexadecimal form, along with some supplemental information where necessary.

Below are some examples of the JSON that would be produced using our extension.

Handling an unknown open type value:

"some-open-type-element" : { 
   "encoding-rules+" : "BER",
   "encoded-data+" : "03020101"
}

Handling unknown SEQUENCE or SET extension elements:

"extensions+" : {
   "encoding-rules+" : "BER",
   "encoded-data+": [ "hex for extension X", "hex for extension Y" ]
}

Handling an unknown CHOICE extension element:

some-choice-field : {
   "extension+" : {
      "encoding-rules+" : "PER",
      "encoded-data+" : "04020301",
      "encoded-per-index+" : 5
   }
}

Easy V2X Conversions with Python

You can now use Python and our V2X ASN.1 API to easily convert binary V2X messages to text – whether JSON or XML – and vice versa.

Our V2X API is a C++ API, but the latest update provides a Python wrapper that can be used to convert V2X ASN.1-encoded data. There are three classes, each with methods for converting between binary (unaligned PER) and text (JSON or XML), in either direction.  The classes are:

  • For SAE J2735 DSRC (Dedicated Short Range Communications):
    • MessageFrame
  • For ETSI ITS:
    • CAM (Cooperative Awareness Message), ETSI EN 302 637-2
    • DENM (Decentralized Environmental Notification Message), ETSI EN 302 637-3

The API kit includes a sample Python program that handles things like using files for input/output and working with hexadecimal representations of the binary data, but at the end of the day, the conversion itself is simple, using one of the following function calls:

  • binary to JSON: buf = cls.to_json(inp_data, len(inp_data))
  • binary to XML: buf = cls.to_xml(inp_data, len(inp_data))
  • JSON to binary: buf = cls.from_json(inp_data)
  • XML to binary: cls.from_xml(inp_data)

(where cls is one of the provided classes: MessageFrame, CAM, or DENM.)

Download our V2X ASN.1 API and give it try!  Be sure to choose one of the 64-bit downloads, as the Python wrapper is not available for 32-bit systems.  Full documentation for the API is available on our website and included in the download.

Improved TBCD and BCD Support for Java/C#

Our next release of ASN1C (v 7.3) will include improved support for TBCD and BCD strings for Java and C#.  In short, for these types, the toString/ToString function will return the TBCD/BCD interpretation of the octets, rather than merely their hexadecimal representation.  This also improves the print functionality.

TBCD stands for Telephony Binary-coded Decimal and BCD stands for Binary-coded Decimal.  So, what are TBCD and BCD strings?  They are OCTET STRINGS in which a series of digits or telephony digits are encoded, using one nibble (4 bits) per digit.  There isn’t an authoritative definition, but there are a few standards out there that provide definitions of TBCD or BCD and these are what we’ve followed, as described below.

As you will see in the following descriptions, TBCD and BCD strings are similar.  The differences are 1) the set of digit characters and 2) the ordering of the nibbles within the bytes.

TBCD Strings

For TBCD, we follow 3GPP 29.002.  This is also the document that happens to be referenced in the section on TBCD in the Wikipedia entry for BCD.  Here is how 29.002 defines TBCD:

TBCD-STRING ::= OCTET STRING
-- This type (Telephony Binary Coded Decimal String) is used to
-- represent several digits from 0 through 9, *, #, a, b, c, two
-- digits per octet, each digit encoded 0000 to 1001 (0 to 9),
-- 1010 (*), 1011 (#), 1100 (a), 1101 (b) or 1110 (c); 1111 used
-- as filler when there is an odd number of digits.
-- bits 8765 of octet n encoding digit 2n
-- bits 4321 of octet n encoding digit 2(n-1) +1

To summarize the characteristics for 3GPP 29.002 TBCD-STRING:
• Uses characters 0-9,*,#,a-c.
• F nibble is used as filler when there is an odd number of digits.
• The low nibble contains the first digit.

Note that 3GPP 24.008 §10.5.4.7 “Called party BCD number” specifies the same encoding, though it simply refers to it as “BCD”.  24.008 also calls for BCD in §10.5.1.4 “Mobile Identity” (for the  IMSI, IMEI and IMEISV), (presumably) meaning BCD as defined in §10.5.4.7, i.e. TBCD.

BCD Strings

For BCD, we have followed the TAP3 (GSM TD.57) specification of BCD.  Here is how they define BCD:

-- The BCDString data type (Binary Coded Decimal String) is used to represent 
-- several digits from 0 through 9, a, b, c, d, e. 
-- Two digits are encoded per octet. The four leftmost bits of the octet represent 
-- the first digit while the four remaining bits represent the following digit. 
-- A single f must be used as a filler when the total number of digits to be 
-- encoded is odd. 
-- No other filler is allowed.

To summarize the characteristics of TAP3 BCDString:

• Uses characters 0-9,a-e.
• F nibble is used as filler when there is an odd number of digits.
• The high nibble contains the first digit.

ITU-T Q.825 TBCD-STRING

Q.825 was another candidate for a definition of TBCD strings.  At this point, we haven’t added special support for it.  This section merely points out the differences between Q.825 TBCD-STRING and 3GPP 29.002 TBCD-STRING.  The differences are:

  • In Q.825, TBCD-STRING is defined as part of an OCTET STRING, not as a standalone type.  Prior to the TBCD-STRING content, the OCTET STRING contains an odd/even indicator octet, and, in some cases, another octet.
  • Q.825 orders the nibbles differently.
  • Q.825 uses the F nibble to mark the end of the TBCD string (“end of pulsing signal-ST”)
  • Q.825 uses the 0 nibble as filler when there is an odd number of digits.  So, in some cases, a zero nibble is merely filler, but in other cases it is a ‘0’ digit.  [Note: we’re not sure why Q.825 specifies that filler is required when there is an odd number of digits; it seem it should be required when there is an even number of digits.  By our reading, “123” would map to 0x123F (no filler), while “1234” would map to 0x12340F (filler).]