NMEA Web Serial
    Preparing search index...

    Function createNmeaMachine

    • Factory function to create an NMEA state machine with a generic adapter pattern.

      Creates an XState state machine that manages serial port connections, parses NMEA sentences, and transforms them into your application's data format using the provided adapter function.

      Type Parameters

      • TData

        The type of computed/translated data stored in context.

      • TPackets extends Record<string, PacketStub<string> | undefined>

        The type of stored packets (typically a record of sentence ID to packet).

      Parameters

      Returns StateMachine<
          NmeaContext<TData, TPackets>,

              | { type: "CONNECT" }
              | { type: "DISCONNECT" }
              | { type: "SERIAL.DATA"; data: Packet }
              | { type: "SERIAL.ERROR"; error: string }
              | { type: "FATAL_ERROR"; error: string }
              | { type: "SERIAL.DISCONNECTED" }
              | { type: "STOP" }
              | { type: "SET_LOGGING"; enabled: boolean }
              | { type: "SET_BAUD_RATE"; baudRate: number },
          {
              [key: string]:
                  | ActorRefFromLogic<
                      PromiseActorLogic<SerialPort, { baudRate: number }, EventObject>,
                  >
                  | ActorRefFromLogic<
                      CallbackActorLogic<NmeaEvent, { port: SerialPort }, EventObject>,
                  >
                  | ActorRefFromLogic<
                      PromiseActorLogic<void, { port: SerialPort | null }, EventObject>,
                  >
                  | undefined;
          },
          ToProvidedActor<
              {},
              {
                  connectToSerial: PromiseActorLogic<
                      SerialPort,
                      { baudRate: number },
                      EventObject,
                  >;
                  readNmeaStream: CallbackActorLogic<
                      NmeaEvent,
                      { port: SerialPort },
                      EventObject,
                  >;
                  closePort: PromiseActorLogic<
                      void,
                      { port: SerialPort
                      | null },
                      EventObject,
                  >;
              },
          >,
          ToParameterizedObject<
              {
                  setPort: { port: SerialPort };
                  setError: { error: unknown };
                  logParsedData: { packet: Packet };
                  storePacket: { packet: Packet };
                  clearError: { error: string };
                  setFatalError: { error: string };
                  disconnect: NonReducibleUnknown;
                  setLogging: { enabled: boolean };
                  setBaudRate: { baudRate: number };
              },
          >,
          never,
          never,
          "error"
          | "connected"
          | "connecting"
          | "disconnected"
          | "disconnecting",
          string,
          NonReducibleUnknown,
          NonReducibleUnknown,
          EventObject,
          MetaObject,
          ToStateSchema<
              {
                  id: "nmea";
                  initial: "disconnected";
                  context: {
                      port: null;
                      error: null;
                      packets: TPackets;
                      data: TData;
                      enableLogging: false;
                      baudRate: 4800;
                  };
                  on: {
                      SET_LOGGING: {
                          actions: {
                              type: "setLogging";
                              params: (
                                  __namedParameters: {
                                      context: NmeaContext;
                                      event: { type: "SET_LOGGING"; enabled: boolean };
                                  },
                              ) => { enabled: boolean };
                          };
                      };
                  };
                  states: {
                      disconnected: {
                          on: {
                              CONNECT: "connecting";
                              SET_BAUD_RATE: {
                                  actions: {
                                      type: "setBaudRate";
                                      params: (
                                          __namedParameters: {
                                              context: NmeaContext;
                                              event: { type: ...; baudRate: ... };
                                          },
                                      ) => { baudRate: number };
                                  };
                              };
                          };
                      };
                      connecting: {
                          invoke: {
                              id: "connectToSerial";
                              src: "connectToSerial";
                              input: (
                                  __namedParameters: {
                                      context: NmeaContext;
                                      event:
                                          | { type: "CONNECT" }
                                          | { type: "DISCONNECT" }
                                          | { type: "SERIAL.DATA"; data: Packet }
                                          | { type: "SERIAL.ERROR"; error: string }
                                          | { type: "FATAL_ERROR"; error: string }
                                          | { type: "SERIAL.DISCONNECTED" }
                                          | { type: "STOP" }
                                          | { type: "SET_LOGGING"; enabled: boolean }
                                          | { type: "SET_BAUD_RATE"; baudRate: number };
                                      self: ActorRef<
                                          MachineSnapshot<
                                              NmeaContext<(...), (...)>,

                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...),
                                              Record<(...), (...)>,
                                              StateValue,
                                              string,
                                              unknown,
                                              any,
                                              any,
                                          >,

                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; data: ... }
                                              | { type: ...; error: ... }
                                              | { type: ...; error: ... }
                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; enabled: ... }
                                              | { type: ...; baudRate: ... },
                                          AnyEventObject,
                                      >;
                                  },
                              ) => { baudRate: number };
                              onDone: {
                                  target: "connected";
                                  actions: {
                                      type: "setPort";
                                      params: (
                                          __namedParameters: {
                                              context: NmeaContext;
                                              event: DoneActorEvent;
                                          },
                                      ) => { port: SerialPort };
                                  };
                              };
                              onError: {
                                  target: "error";
                                  actions: {
                                      type: "setError";
                                      params: (
                                          __namedParameters: {
                                              context: NmeaContext;
                                              event: ErrorActorEvent;
                                          },
                                      ) => { error: unknown };
                                  };
                              };
                          };
                      };
                      connected: {
                          on: {
                              "SERIAL.DATA": {
                                  actions: readonly [
                                      {
                                          type: "logParsedData";
                                          params: (
                                              __namedParameters: { context: ...; event: ... },
                                          ) => { packet: ... };
                                      },
                                      {
                                          type: "storePacket";
                                          params: (
                                              __namedParameters: { context: ...; event: ... },
                                          ) => { packet: ... };
                                      },
                                  ];
                              };
                              "SERIAL.ERROR": {
                                  actions: {
                                      type: "clearError";
                                      params: (
                                          __namedParameters: {
                                              context: NmeaContext;
                                              event: { type: ...; error: ... };
                                          },
                                      ) => { error: string };
                                  };
                              };
                              FATAL_ERROR: {
                                  target: "error";
                                  actions: {
                                      type: "setFatalError";
                                      params: (
                                          __namedParameters: {
                                              context: NmeaContext;
                                              event: { type: ...; error: ... };
                                          },
                                      ) => { error: string };
                                  };
                              };
                              "SERIAL.DISCONNECTED": { target: "disconnecting" };
                              DISCONNECT: {
                                  actions: ActionFunction<
                                      NmeaContext<TData, TPackets>,
                                      { type: "DISCONNECT" },

                                          | { type: "CONNECT" }
                                          | { type: "DISCONNECT" }
                                          | { type: "SERIAL.DATA"; data: Packet }
                                          | { type: "SERIAL.ERROR"; error: string }
                                          | { type: "FATAL_ERROR"; error: string }
                                          | { type: "SERIAL.DISCONNECTED" }
                                          | { type: "STOP" }
                                          | { type: "SET_LOGGING"; enabled: boolean }
                                          | { type: "SET_BAUD_RATE"; baudRate: number },
                                      undefined,
                                      never,
                                      never,
                                      never,
                                      never,
                                      never,
                                  >;
                              };
                          };
                          invoke: {
                              id: "streamReader";
                              src: "readNmeaStream";
                              input: (
                                  __namedParameters: {
                                      context: NmeaContext;
                                      event:
                                          | { type: "CONNECT" }
                                          | { type: "DISCONNECT" }
                                          | { type: "SERIAL.DATA"; data: Packet }
                                          | { type: "SERIAL.ERROR"; error: string }
                                          | { type: "FATAL_ERROR"; error: string }
                                          | { type: "SERIAL.DISCONNECTED" }
                                          | { type: "STOP" }
                                          | { type: "SET_LOGGING"; enabled: boolean }
                                          | { type: "SET_BAUD_RATE"; baudRate: number };
                                      self: ActorRef<
                                          MachineSnapshot<
                                              NmeaContext<(...), (...)>,

                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...),
                                              Record<(...), (...)>,
                                              StateValue,
                                              string,
                                              unknown,
                                              any,
                                              any,
                                          >,

                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; data: ... }
                                              | { type: ...; error: ... }
                                              | { type: ...; error: ... }
                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; enabled: ... }
                                              | { type: ...; baudRate: ... },
                                          AnyEventObject,
                                      >;
                                  },
                              ) => { port: SerialPort };
                          };
                      };
                      disconnecting: {
                          invoke: {
                              id: "closePort";
                              src: "closePort";
                              input: (
                                  __namedParameters: {
                                      context: NmeaContext;
                                      event:
                                          | { type: "CONNECT" }
                                          | { type: "DISCONNECT" }
                                          | { type: "SERIAL.DATA"; data: Packet }
                                          | { type: "SERIAL.ERROR"; error: string }
                                          | { type: "FATAL_ERROR"; error: string }
                                          | { type: "SERIAL.DISCONNECTED" }
                                          | { type: "STOP" }
                                          | { type: "SET_LOGGING"; enabled: boolean }
                                          | { type: "SET_BAUD_RATE"; baudRate: number };
                                      self: ActorRef<
                                          MachineSnapshot<
                                              NmeaContext<(...), (...)>,

                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...)
                                                  | (...),
                                              Record<(...), (...)>,
                                              StateValue,
                                              string,
                                              unknown,
                                              any,
                                              any,
                                          >,

                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; data: ... }
                                              | { type: ...; error: ... }
                                              | { type: ...; error: ... }
                                              | { type: ... }
                                              | { type: ... }
                                              | { type: ...; enabled: ... }
                                              | { type: ...; baudRate: ... },
                                          AnyEventObject,
                                      >;
                                  },
                              ) => { port: SerialPort
                              | null };
                              onDone: { target: "disconnected"; actions: "disconnect" };
                              onError: { target: "disconnected"; actions: "disconnect" };
                          };
                      };
                      error: { on: { CONNECT: "connecting" } };
                  };
              },
          >,
      >

      An XState state machine that can be used with createActor from XState.

      const machine = createNmeaMachine({
        adapter: computeNavigationData,
        allowedSentenceIds: ['GGA', 'RMC', 'VTG'],
        initialData: { time: null, position: null },
        initialPackets: {},
      });

      const actor = createActor(machine);
      actor.start();
      actor.send({ type: 'CONNECT' });

      The returned machine is an XState state machine. Use it with XState's createActor to create an actor instance, or use the NmeaClient class for a simpler API that doesn't require direct XState knowledge.

    Settings

    Member Visibility