chirpstack · nicolas-juteau · Mar 18, 2025 · Mar 24, 2025 · Mar 25, 2025 · Mar 25, 2025
diff --git a/api/proto/api/device_profile.proto b/api/proto/api/device_profile.proto
@@ -24,6 +24,9 @@ enum CodecRuntime {
 
   // JavaScript.
   JS = 2;
+
+  // JavaScript plugin.
+  JS_PLUGIN = 3;
 }
 
 enum MeasurementKind {
@@ -178,6 +181,14 @@ service DeviceProfileService {
       get : "/api/device-profiles/adr-algorithms"
     };
   }
+
+  // List available codec plugins.
+  rpc ListCodecPlugins(google.protobuf.Empty)
+      returns (ListDeviceProfileCodecPluginsResponse) {
+    option (google.api.http) = {
+      get : "/api/device-profiles/codec-plugins"
+    };
+  }
 }
 
 message DeviceProfile {
@@ -457,6 +468,9 @@ message DeviceProfile {
 
   // Application Layer parameters.
   AppLayerParams app_layer_params = 54;
+
+  // Payload codec plugin ID.
+  string codec_plugin_id = 55;
 }
 
 message Measurement {
@@ -593,3 +607,19 @@ message AdrAlgorithmListItem {
   // Algorithm name.
   string name = 2;
 }
+
+message ListDeviceProfileCodecPluginsResponse {
+  // Total number of plugins.
+  uint32 total_count = 1;
+
+  // Result-set.
+  repeated CodecPluginListItem result = 2;
+}
+
+message CodecPluginListItem {
+  // Pluigin ID.
+  string id = 1;
+
+  // Plugin name.
+  string name = 2;
+}
diff --git a/api/proto/api/device_profile_template.proto b/api/proto/api/device_profile_template.proto
@@ -157,6 +157,9 @@ message DeviceProfileTemplate {
     // keys of the decoded payload. In cases where the decoded payload contains
     // random keys in the data, you want to set this to false.
     bool auto_detect_measurements = 29;
+
+    // Payload codec plugin ID.
+    string codec_plugin_id = 30;
 }
 
 message DeviceProfileTemplateListItem {

diff --git a/api/rust/proto/chirpstack/api/device_profile.proto b/api/rust/proto/chirpstack/api/device_profile.proto
@@ -24,6 +24,9 @@ enum CodecRuntime {
 
   // JavaScript.
   JS = 2;
+
+  // JavaScript plugin.
+  JS_PLUGIN = 3;
 }
 
 enum MeasurementKind {
@@ -178,6 +181,14 @@ service DeviceProfileService {
       get : "/api/device-profiles/adr-algorithms"
     };
   }
+
+  // List available codec plugins.
+  rpc ListCodecPlugins(google.protobuf.Empty)
+      returns (ListDeviceProfileCodecPluginsResponse) {
+    option (google.api.http) = {
+      get : "/api/device-profiles/codec-plugins"
+    };
+  }
 }
 
 message DeviceProfile {
@@ -457,6 +468,9 @@ message DeviceProfile {
 
   // Application Layer parameters.
   AppLayerParams app_layer_params = 54;
+
+  // Payload codec plugin ID.
+  string codec_plugin_id = 55;
 }
 
 message Measurement {
@@ -593,3 +607,19 @@ message AdrAlgorithmListItem {
   // Algorithm name.
   string name = 2;
 }
+
+message ListDeviceProfileCodecPluginsResponse {
+  // Total number of plugins.
+  uint32 total_count = 1;
+
+  // Result-set.
+  repeated CodecPluginListItem result = 2;
+}
+
+message CodecPluginListItem {
+  // Pluigin ID.
+  string id = 1;
+
+  // Plugin name.
+  string name = 2;
+}
diff --git a/api/rust/proto/chirpstack/api/device_profile_template.proto b/api/rust/proto/chirpstack/api/device_profile_template.proto
@@ -157,6 +157,9 @@ message DeviceProfileTemplate {
     // keys of the decoded payload. In cases where the decoded payload contains
     // random keys in the data, you want to set this to false.
     bool auto_detect_measurements = 29;
+
+    // Payload codec plugin ID.
+    string codec_plugin_id = 30;
 }
 
 message DeviceProfileTemplateListItem {

diff --git a/chirpstack/migrations_postgres/2025-03-17-100300_add_codec_plugin_id/down.sql b/chirpstack/migrations_postgres/2025-03-17-100300_add_codec_plugin_id/down.sql
@@ -0,0 +1,5 @@
+alter table device_profile
+    drop column codec_plugin_id;
+
+alter table device_profile_template
+    drop column codec_plugin_id;
diff --git a/chirpstack/migrations_postgres/2025-03-17-100300_add_codec_plugin_id/up.sql b/chirpstack/migrations_postgres/2025-03-17-100300_add_codec_plugin_id/up.sql
@@ -0,0 +1,5 @@
+alter table device_profile
+    add column codec_plugin_id varchar(100) not null default '';
+
+alter table device_profile_template
+    add column codec_plugin_id varchar(100) not null default '';
diff --git a/chirpstack/migrations_sqlite/2025-03-17-100300_add_codec_plugin_id/down.sql b/chirpstack/migrations_sqlite/2025-03-17-100300_add_codec_plugin_id/down.sql
@@ -0,0 +1,5 @@
+alter table device_profile
+    drop column codec_plugin_id;
+
+alter table device_profile_template
+    drop column codec_plugin_id;
diff --git a/chirpstack/migrations_sqlite/2025-03-17-100300_add_codec_plugin_id/up.sql b/chirpstack/migrations_sqlite/2025-03-17-100300_add_codec_plugin_id/up.sql
@@ -0,0 +1,5 @@
+alter table device_profile
+    add column codec_plugin_id varchar(100) not null default '';
+
+alter table device_profile_template
+    add column codec_plugin_id varchar(100) not null default '';
diff --git a/chirpstack/src/api/device.rs b/chirpstack/src/api/device.rs
@@ -1087,6 +1087,7 @@ impl DeviceService for Device {
                 req_qi.f_port as u8,
                 &dev.variables,
                 &dp.payload_codec_script,
+                &dp.codec_plugin_id,
                 obj,
             )
             .await

diff --git a/chirpstack/src/api/device_profile.rs b/chirpstack/src/api/device_profile.rs
@@ -11,6 +11,7 @@ use super::error::ToStatus;
 use super::helpers;
 use super::helpers::{FromProto, ToProto};
 use crate::adr;
+use crate::codec;
 use crate::storage::{device_profile, fields};
 
 pub struct DeviceProfile {
@@ -52,6 +53,7 @@ impl DeviceProfileService for DeviceProfile {
             mac_version: req_dp.mac_version().from_proto(),
             reg_params_revision: req_dp.reg_params_revision().from_proto(),
             adr_algorithm_id: req_dp.adr_algorithm_id.clone(),
+            codec_plugin_id: req_dp.codec_plugin_id.clone(),
             payload_codec_runtime: req_dp.payload_codec_runtime().from_proto(),
             payload_codec_script: req_dp.payload_codec_script.clone(),
             flush_queue_on_activate: req_dp.flush_queue_on_activate,
@@ -196,6 +198,7 @@ impl DeviceProfileService for DeviceProfile {
                 mac_version: dp.mac_version.to_proto().into(),
                 reg_params_revision: dp.reg_params_revision.to_proto().into(),
                 adr_algorithm_id: dp.adr_algorithm_id,
+                codec_plugin_id: dp.codec_plugin_id,
                 payload_codec_runtime: dp.payload_codec_runtime.to_proto().into(),
                 payload_codec_script: dp.payload_codec_script,
                 flush_queue_on_activate: dp.flush_queue_on_activate,
@@ -308,6 +311,7 @@ impl DeviceProfileService for DeviceProfile {
             mac_version: req_dp.mac_version().from_proto(),
             reg_params_revision: req_dp.reg_params_revision().from_proto(),
             adr_algorithm_id: req_dp.adr_algorithm_id.clone(),
+            codec_plugin_id: req_dp.codec_plugin_id.clone(),
             payload_codec_runtime: req_dp.payload_codec_runtime().from_proto(),
             payload_codec_script: req_dp.payload_codec_script.clone(),
             flush_queue_on_activate: req_dp.flush_queue_on_activate,
@@ -525,6 +529,33 @@ impl DeviceProfileService for DeviceProfile {
             result,
         }))
     }
+
+    async fn list_codec_plugins(
+        &self,
+        request: Request<()>,
+    ) -> Result<Response<api::ListDeviceProfileCodecPluginsResponse>, Status> {
+        self.validator
+            .validate(
+                request.extensions(),
+                validator::ValidateActiveUserOrKey::new(),
+            )
+            .await?;
+
+        let items = codec::js_plugin::get_plugins().await;
+        let mut result: Vec<api::CodecPluginListItem> = items
+            .iter()
+            .map(|(k, v)| api::CodecPluginListItem {
+                id: k.clone(),
+                name: v.clone(),
+            })
+            .collect();
+        result.sort_by(|a, b| a.name.cmp(&b.name));
+
+        Ok(Response::new(api::ListDeviceProfileCodecPluginsResponse {
+            total_count: items.len() as u32,
+            result,
+        }))
+    }
 }
 
 #[cfg(test)]
@@ -574,6 +605,7 @@ pub mod test {
                     mac_version: common::MacVersion::Lorawan103.into(),
                     reg_params_revision: common::RegParamsRevision::A.into(),
                     adr_algorithm_id: "default".into(),
+                    codec_plugin_id: "passthrough".into(),
                     ..Default::default()
                 }),
             },
@@ -606,6 +638,7 @@ pub mod test {
                     ts005_version: api::Ts005Version::Ts005NotImplemented.into(),
                     ts005_f_port: 200,
                 }),
+                codec_plugin_id: "passthrough".into(),
                 ..Default::default()
             }),
             get_resp.get_ref().device_profile
@@ -623,6 +656,7 @@ pub mod test {
                     mac_version: common::MacVersion::Lorawan103.into(),
                     reg_params_revision: common::RegParamsRevision::A.into(),
                     adr_algorithm_id: "default".into(),
+                    codec_plugin_id: "passthrough".into(),
                     ..Default::default()
                 }),
             },
@@ -647,6 +681,7 @@ pub mod test {
                 reg_params_revision: common::RegParamsRevision::A.into(),
                 adr_algorithm_id: "default".into(),
                 app_layer_params: Some(api::AppLayerParams::default()),
+                codec_plugin_id: "passthrough".into(),
                 ..Default::default()
             }),
             get_resp.get_ref().device_profile
@@ -697,6 +732,17 @@ pub mod test {
         assert_eq!("default", list_adr_algs_resp.result[0].id);
         assert_eq!("lr_fhss", list_adr_algs_resp.result[1].id);
         assert_eq!("lora_lr_fhss", list_adr_algs_resp.result[2].id);
+
+        // list codec plugins
+        let list_codec_plugins_req = get_request(&u.id, ());
+        let list_codec_plugins_resp = service
+            .list_codec_plugins(list_codec_plugins_req)
+            .await
+            .unwrap();
+        let list_codec_plugins_resp = list_codec_plugins_resp.get_ref();
+        assert_eq!(1, list_codec_plugins_resp.total_count);
+        assert_eq!(1, list_codec_plugins_resp.result.len());
+        assert_eq!("passthrough", list_codec_plugins_resp.result[0].id);
     }
 
     fn get_request<T>(user_id: &Uuid, req: T) -> Request<T> {

diff --git a/chirpstack/src/api/device_profile_template.rs b/chirpstack/src/api/device_profile_template.rs
@@ -51,6 +51,7 @@ impl DeviceProfileTemplateService for DeviceProfileTemplate {
             mac_version: req_dp.mac_version().from_proto(),
             reg_params_revision: req_dp.reg_params_revision().from_proto(),
             adr_algorithm_id: req_dp.adr_algorithm_id.clone(),
+            codec_plugin_id: req_dp.codec_plugin_id.clone(),
             payload_codec_runtime: req_dp.payload_codec_runtime().from_proto(),
             payload_codec_script: req_dp.payload_codec_script.clone(),
             flush_queue_on_activate: req_dp.flush_queue_on_activate,
@@ -123,6 +124,7 @@ impl DeviceProfileTemplateService for DeviceProfileTemplate {
                 mac_version: dp.mac_version.to_proto().into(),
                 reg_params_revision: dp.reg_params_revision.to_proto().into(),
                 adr_algorithm_id: dp.adr_algorithm_id,
+                codec_plugin_id: dp.codec_plugin_id,
                 payload_codec_runtime: dp.payload_codec_runtime.to_proto().into(),
                 payload_codec_script: dp.payload_codec_script,
                 flush_queue_on_activate: dp.flush_queue_on_activate,
@@ -192,6 +194,7 @@ impl DeviceProfileTemplateService for DeviceProfileTemplate {
             mac_version: req_dp.mac_version().from_proto(),
             reg_params_revision: req_dp.reg_params_revision().from_proto(),
             adr_algorithm_id: req_dp.adr_algorithm_id.clone(),
+            codec_plugin_id: req_dp.codec_plugin_id.clone(),
             payload_codec_runtime: req_dp.payload_codec_runtime().from_proto(),
             payload_codec_script: req_dp.payload_codec_script.clone(),
             flush_queue_on_activate: req_dp.flush_queue_on_activate,
@@ -338,6 +341,7 @@ pub mod test {
                     mac_version: common::MacVersion::Lorawan103.into(),
                     reg_params_revision: common::RegParamsRevision::A.into(),
                     adr_algorithm_id: "default".into(),
+                    codec_plugin_id: "passthrough".into(),
                     ..Default::default()
                 }),
             },
@@ -362,6 +366,7 @@ pub mod test {
                 mac_version: common::MacVersion::Lorawan103.into(),
                 reg_params_revision: common::RegParamsRevision::A.into(),
                 adr_algorithm_id: "default".into(),
+                codec_plugin_id: "passthrough".into(),
                 ..Default::default()
             }),
             get_resp.get_ref().device_profile_template
@@ -380,6 +385,7 @@ pub mod test {
                     mac_version: common::MacVersion::Lorawan103.into(),
                     reg_params_revision: common::RegParamsRevision::A.into(),
                     adr_algorithm_id: "default".into(),
+                    codec_plugin_id: "passthrough".into(),
                     ..Default::default()
                 }),
             },
@@ -404,6 +410,7 @@ pub mod test {
                 mac_version: common::MacVersion::Lorawan103.into(),
                 reg_params_revision: common::RegParamsRevision::A.into(),
                 adr_algorithm_id: "default".into(),
+                codec_plugin_id: "passthrough".into(),
                 ..Default::default()
             }),
             get_resp.get_ref().device_profile_template

diff --git a/chirpstack/src/api/helpers.rs b/chirpstack/src/api/helpers.rs
@@ -133,6 +133,7 @@ impl ToProto<api::CodecRuntime> for Codec {
             Codec::NONE => api::CodecRuntime::None,
             Codec::CAYENNE_LPP => api::CodecRuntime::CayenneLpp,
             Codec::JS => api::CodecRuntime::Js,
+            Codec::JS_PLUGIN => api::CodecRuntime::JsPlugin,
         }
     }
 }
@@ -143,6 +144,7 @@ impl FromProto<Codec> for api::CodecRuntime {
             api::CodecRuntime::None => Codec::NONE,
             api::CodecRuntime::CayenneLpp => Codec::CAYENNE_LPP,
             api::CodecRuntime::Js => Codec::JS,
+            api::CodecRuntime::JsPlugin => Codec::JS_PLUGIN,
         }
     }
 }

diff --git a/chirpstack/src/cmd/configfile.rs b/chirpstack/src/cmd/configfile.rs
@@ -573,6 +573,16 @@ pub fn run() {
     # Maximum execution time.
     max_execution_time="{{ codec.js.max_execution_time }}"
 
+    # Custom codec plugins.
+    #
+    # The custom codec plugin must be implemented in JavaScript. For an example
+    # skeleton, please see file examples/custom_plugins/plugin_skeleton.js
+    plugins=[
+      {{#each codec.js.plugins}}
+      "{{this}}",
+      {{/each}}
+    ]
+
 
 # User authentication configuration.
 [user_authentication]

diff --git a/chirpstack/src/cmd/root.rs b/chirpstack/src/cmd/root.rs
@@ -5,7 +5,7 @@ use signal_hook_tokio::Signals;
 use tracing::{info, warn};
 
 use crate::gateway;
-use crate::{adr, api, applayer::fuota, backend, downlink, integration, region, storage};
+use crate::{adr, api, applayer::fuota, backend, codec, downlink, integration, region, storage};
 
 pub async fn run() -> Result<()> {
     info!(
@@ -18,6 +18,7 @@ pub async fn run() -> Result<()> {
     region::setup()?;
     backend::setup().await?;
     adr::setup().await?;
+    codec::js_plugin::setup().await?;
     integration::setup().await?;
     gateway::backend::setup().await?;
     downlink::setup().await;

diff --git a/chirpstack/src/codec/js/mod.rs b/chirpstack/src/codec/js/mod.rs
@@ -8,9 +8,9 @@ use rquickjs::{CatchResultExt, IntoJs};
 use super::convert;
 use crate::config;
 
-mod vendor_base64_js;
-mod vendor_buffer;
-mod vendor_ieee754;
+pub mod vendor_base64_js;
+pub mod vendor_buffer;
+pub mod vendor_ieee754;
 
 pub async fn decode(
     recv_time: DateTime<Utc>,