Decoda - J1939

This is a utility service for decoding the data from a J1939 payload. It began as a personal side project, but it should be useful if you find yourself with some J1939 frames and only the PDFs from SAE to decode them! 😉

See examples Swagger UI

What is J1939?

Society of Automotive Engineers standard SAE J1939 is the vehicle bus recommended practice used for communication and diagnostics among vehicle components. Originating in the car and heavy-duty truck industry in the United States, it is now widely used in other parts of the world.

It defines a range of aspects of how to communicate - including physical layer, data link, etc - which allows computer systems within trucks and heavy vehiles to hopefully interoperate. It utilises the Controller Area Network (CAN bus) standard for the underlying physical and link layers.

There are plenty of good resources for learning about J1939 - the standard itself, and other sites on the internet. In particular, there is a very good explanation by Burkhard Stubert on his website called Introduction to the SAE J1939 Standard. The examples from that site are great to try with the Swagger UI.

What is this service?

This is a RESTFul web service that can decode binary data according to the PGNs and SPNs.

The J1939 standard specifies more 'application level' information than you might find in many other standards (IEEE ones for instance). It includes a few thousand pages specifying parameters to be communicated, called Suspect Parameter Numbers (SPNs); the accepted groupings of these parameters, called Parameter Group Numebrs (PGNs); and how to pack them into frames on the underlying CAN bus. If you understand J1939 even a bit, you'll understand what this means.

Examples

Looking up a PGN

For example, you might want to look up what PGN 0 is.

GET /v1/reference/pgn/0

{
  "description": "",
  "id": 0,
  "length": 8,
  "name": "Torque/Speed Control 1"
}

Convert a CAN Id to its parts

J1939 uses a 29-bit identifier for conveying the priority, the PGN number and the source address of a frame. The bit encoding looks like this:

For example, the API can decode a CAN Id into its component parts:

GET /v1/decode/canid/0

{
  "da": {
    "name": "Engine #1",
    "num": 0
  },
  "pgn": {
    "description": "",
    "id": 0,
    "length": 8,
    "name": "Torque/Speed Control 1"
  },
  "priority": 0,
  "sa": {
    "name": "Engine #1",
    "num": 0
  }
}

Decode a frame payload

The real meat of this API is decoding the J1939 frame payloads into something more readable.

For example, try various payloads for the PGN 0 - Torque/Speed Control 1:

GET /v1/decode/pgn/0/123456789abcdef0

{
  "header": {
    "pgn": {
      "description": "",
      "id": 0,
      "length": 8,
      "name": "Torque/Speed Control 1"
    }
  },
  "values": [
    {
      "display": "Torque control - Control torque to the included \"desired torque\" value. (2)",
      "id": 695,
      "name": "Engine Override Control Mode",
      "value": "Torque control - Control torque to the included \"desired torque\" value."
    },
    {
      "display": "Transient Optimized for driveline disengaged and non-lockup conditions (0)",
      "id": 696,
      "name": "Engine Requested Speed Control Conditions",
      "value": "Transient Optimized for driveline disengaged and non-lockup conditions"
    },
    {
      "display": "High priority (1)",
      "id": 897,
      "name": "Override Control Mode Priority",
      "value": "High priority"
    },
    {
      "display": "2758.5 rpm",
      "id": 898,
      "name": "Engine Requested Speed/Speed Limit",
      "value": 2758.5
    },
    {
      "display": "-5 %",
      "id": 518,
      "name": "Engine Requested Torque/Torque Limit",
      "value": -5
    },
    {
      "display": "500 ms transmission rate (2)",
      "id": 3349,
      "name": "TSC1 Transmission Rate",
      "value": "500 ms transmission rate"
    },
    {
      "display": "P6-P31 = Reserved for SAE Assignment (19)",
      "id": 3350,
      "name": "TSC1 Control Purpose",
      "value": "P6-P31 = Reserved for SAE Assignment"
    },
    {
      "display": "0.875 % (encoded value 1.5 % is more than max)",
      "id": 4191,
      "name": "Engine Requested Torque -  High Resolution",
      "value": 0.875
    },
    {
      "display": "0 count",
      "id": 4206,
      "name": "Message Counter",
      "value": 0
    },
    {
      "display": "15 count",
      "id": 4207,
      "name": "Message Checksum",
      "value": 15
    }
  ]
}
        

Swagger UI

The API has a Swagger definition. You can find the API specification at /v1/swagger.json and a full Swagger UI (complete with examples) at /v1/ui.

FAQ

How thoroughly tested is this service?

The implementation is thoroughly tested, BUT the results of the decodings have not been validated, and thus may contain errors. We recommend that you do a bit of your own validation on the result before you bet the house on them. Also, if you find what you think is an error, please contact us about it

Is it really free?

Yes, to a point. The API has some rate limiting on it, but for now it is free. If you would like to use this beyond the rate limits, please make contact and we can come to an arrangement.

Can I get the source?

At this stage the service is offered just as a RESTFul web service. If this is not suitable (i.e. you want to use the decoding in a context without internet access), then please make contact and we can hopefully come to an arrangement.

Why did you make this?

I think the J1939 spec is pretty cool, but quite unapproachable...and I thought it would be a good challenge.

Is this a creative commons project?

No unfortunately it is not (at this stage). The CC domains are cheap, and have a fleeting relationship to my home country.

Contact

Email us at support@decoda.cc