Membangun TCP Listener untuk GPS Device di Go



Bayangkan 500 GPS tracker nyambung ke server bersamaan. Masing-masing kirim posisi tiap 10-30 detik, sementara sebagian cuma kirim heartbeat kalau lagi diam. Koneksinya bisa awet berjam-jam, putus tanpa pamit, atau kirim data dalam potongan-potongan. Ehem, ramai sekali.

Kalau kamu terbiasa dengan HTTP API, ingat bahwa TCP sendiri tidak punya struktur request-response. Listener cuma menerima aliran byte, dan aplikasilah yang harus menafsirkannya.

Di Part 1 kita sudah membahas cara device berkomunikasi lewat koneksi TCP persisten dan paket binary dengan aturan berbeda di tiap vendor. Nah, di sini kita bikin TCP listener di Go untuk menerima koneksi-koneksi itu.

Polanya sama dengan yang menangani ratusan device di sistem produksi saya. Implementasinya hanya pakai standard library Go, tanpa framework.

Yang Kita Bangun di Artikel Ini #

Targetnya satu program kecil yang:

  1. Menerima banyak koneksi secara concurrent, satu goroutine per koneksi
  2. Menyusun ulang frame GT06 dari stream TCP mentah (bagian ini yang paling sering bikin salah)
  3. Memutus koneksi “zombie” yang sudah mati tanpa kabar
  4. Mati dengan sopan saat di-deploy ulang (graceful shutdown)

Kita belum akan men-decode isi paket, menyimpan data ke database, atau menambah antrean pesan. Paket login, paket posisi, dan balasan ACK yang valid butuh CRC-ITU; itu dibahas di Part 3. Listener cukup menerima dan menyusun frame, urusan setelahnya belakangan.

TCP Server Dasar #

Kita mulai dari server paling sederhana:

listener, err := net.Listen("tcp", ":5094")
if err != nil {
    log.Fatal(err)
}
defer listener.Close()

for {
    conn, err := listener.Accept()
    if err != nil {
        log.Printf("accept error: %v", err)
        continue
    }
    go handleConnection(conn)
}

net.Listen membuka port, lalu loop Accept menerima koneksi. Setiap koneksi ditangani goroutine sendiri. Goroutine itu murah: stack awalnya cuma beberapa kilobyte, bukan megabyte seperti thread OS. Jadi pola “satu goroutine per koneksi” tetap ringan saat koneksinya banyak.

Untuk GPS listener, saya tidak menyarankan HTTP: ada overhead header per request, koneksi berumur pendek, dan parsing HTTP tidak berguna untuk paket binary mentah. Lagipula device kamu tidak kirim Content-Type hehe.

Jebakan Pertama: TCP Itu Stream, Bukan Pesan #

Ini beda utama antara TCP listener GPS dan HTTP handler.

Kode HTTP terbiasa dengan asumsi: satu request = satu paket utuh. Di TCP tidak ada jaminan begitu. conn.Read(buf) cuma bilang “kasih aku byte yang ada sekarang”, artinya:

Kalau hasil Read dianggap satu paket utuh, proses decode bisa gagal secara acak, dan masalahnya gampang disangka dari device. (Saya pernah. Lama.)

Solusinya framing manual. Kita pakai bufio.Reader untuk membaca stream, cari start bit GT06 (0x78 0x78), baca length, lalu ambil sisa frame sesuai panjangnya:

// readFrame membaca satu frame GT06 dari stream:
//
//	78 78 | len | protocol | data | serial | crc | 0D 0A
func readFrame(r *bufio.Reader) ([]byte, error) {
	// 1. sinkronisasi: buang byte sampai ketemu start bit 78 78
	for {
		b, err := r.ReadByte()
		if err != nil {
			return nil, err
		}
		if b != 0x78 {
			continue // byte sampah, lewati
		}
		b2, err := r.ReadByte()
		if err != nil {
			return nil, err
		}
		if b2 != 0x78 {
			continue // 0x78 tunggal, bukan start bit; lanjut cari
		}
		break
	}

	frame := []byte{0x78, 0x78}

	// 2. baca length (1 byte: jumlah byte protocol sampai CRC, inklusif)
	lenByte, err := r.ReadByte()
	if err != nil {
		return nil, err
	}
	frame = append(frame, lenByte)

	// 3. tarik sisa frame: len + 2 byte (isi + CRC + stop bit 0D 0A)
	rest := make([]byte, int(lenByte)+2)
	if _, err := io.ReadFull(r, rest); err != nil {
		return nil, err
	}
	frame = append(frame, rest...)

	// 4. validasi stop bit
	if frame[len(frame)-2] != 0x0D || frame[len(frame)-1] != 0x0A {
		return nil, fmt.Errorf("stop bit tidak valid: %X", frame[len(frame)-2:])
	}
	return frame, nil
}

io.ReadFull menunggu sampai buffer terisi penuh, jadi byte yang datang terpotong-potong tetap tersusun jadi satu frame. bufio.Reader menyimpan byte yang belum terpakai; kalau dua frame datang berurutan, byte frame kedua tetap tersedia untuk pembacaan berikutnya.

Ingat aturan framing dari Part 1: angka len dihitung dari protocol number sampai CRC inklusif. Itulah kenapa setelah length byte kita tarik len + 2 byte lagi (isi frame + CRC + stop bit).

handleConnection: Loop Baca Frame #

Dengan framing tadi, handler tinggal membaca frame dari tiap koneksi:

func handleConnection(ctx context.Context, conn net.Conn) {
	defer conn.Close()
	remote := conn.RemoteAddr().String()
	log.Printf("connected: %s", remote)

	reader := bufio.NewReader(conn)
	for {
		conn.SetReadDeadline(time.Now().Add(readTimeout))

		frame, err := readFrame(reader)
		if err != nil {
			if errors.Is(err, io.EOF) {
				log.Printf("disconnected: %s", remote)
			} else if ctx.Err() == nil {
				log.Printf("read error (%s): %v", remote, err)
			}
			return
		}
		log.Printf("frame from %s: %X (%d bytes)", remote, frame, len(frame))
		// TODO part 3: decode payload + balas ACK valid (butuh CRC-ITU)
	}
}

Untuk sekarang, handler cuma mencatat frame dalam format hex. Di Part 3, baris TODO itu kita ganti dengan decoder.

Koneksi Zombie dan Read Deadline #

Baris conn.SetReadDeadline(...) menentukan berapa lama handler menunggu data.

Device GPS di jaringan GSM bisa putus tanpa mengirim paket penutup TCP (FIN), misalnya karena sinyal hilang, baterai dicabut, atau carrier me-reset koneksi. Server lalu masih mencatat koneksi yang sudah mati tapi dikira hidup. Kalau dibiarkan, koneksi begini menumpuk dan menghabiskan file descriptor.

Dengan SetReadDeadline, kalau tidak ada byte yang datang sebelum batas waktu, Read gagal dengan timeout error. Handler keluar dan koneksi ditutup.

Deadline harus lebih besar dari interval heartbeat device. Seperti di Part 1, device yang diam mengirim heartbeat tiap 2-5 menit. Deadline 90 detik akan memutus device sehat yang cuma lagi diam. Makanya nilainya saya set:

// harus LEBIH BESAR dari interval heartbeat device (GT06: 2-5 menit saat idle)
var readTimeout = 10 * time.Minute

Deadline di-reset setiap kali frame berhasil dibaca, sehingga device yang aktif tetap terhubung.

Mati dengan Sopan: Graceful Shutdown #

Listener production bisa di-restart saat deploy, scaling, atau pemeliharaan. Saat container atau sistem dihentikan, OS biasanya mengirim sinyal SIGTERM dan memberi proses waktu untuk menutup diri sebelum dimatikan paksa.

Waktu itu kita pakai untuk menutup listener, menutup koneksi aktif, dan menunggu goroutine selesai sebelum program keluar.

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	listener, err := net.Listen("tcp", ":5094")
	if err != nil {
		log.Fatal(err)
	}

	var wg sync.WaitGroup
	conns := newConnTracker()

	// goroutine penutup: saat sinyal datang, tutup listener + semua koneksi aktif
	go func() {
		<-ctx.Done()
		log.Println("shutting down: menutup listener dan koneksi aktif")
		listener.Close()
		conns.CloseAll()
	}()

	log.Println("listening on :5094")
	for {
		conn, err := listener.Accept()
		if err != nil {
			if ctx.Err() != nil {
				break // shutdown: keluar dari accept loop
			}
			log.Printf("accept error: %v", err)
			continue
		}
		wg.Add(1)
		conns.Add(conn)
		go func() {
			defer wg.Done()
			defer conns.Remove(conn)
			handleConnection(ctx, conn)
		}()
	}

	wg.Wait()
	log.Println("bye")
}

connTracker menyimpan koneksi aktif agar semuanya bisa ditutup sekaligus:

type connTracker struct {
	mu    sync.Mutex
	conns map[net.Conn]struct{}
}

func newConnTracker() *connTracker {
	return &connTracker{conns: make(map[net.Conn]struct{})}
}

func (t *connTracker) Add(c net.Conn) {
	t.mu.Lock()
	t.conns[c] = struct{}{}
	t.mu.Unlock()
}

func (t *connTracker) Remove(c net.Conn) {
	t.mu.Lock()
	delete(t.conns, c)
	t.mu.Unlock()
}

func (t *connTracker) CloseAll() {
	t.mu.Lock()
	defer t.mu.Unlock()
	for c := range t.conns {
		c.Close()
	}
}

signal.NotifyContext mengubah SIGTERM atau Ctrl+C menjadi ctx.Done(). Goroutine penutup menutup listener, sehingga Accept gagal dan loop utama berhenti, lalu menutup koneksi aktif. sync.WaitGroup menunggu semua handler selesai sebelum main keluar.

Menguji Tanpa Device Asli #

Kamu bisa mencoba kode ini tanpa tracker fisik. Fitur /dev/tcp di Bash cukup untuk mengirim data seolah-olah dari device GT06:

exec 3<>/dev/tcp/127.0.0.1/5094
printf '\x78\x78\x0d\x01\x01\x23\x45\x67\x89\x01\x23\x45\x00\x01\x8c\xdd\x0d\x0a' >&3

Itu frame login GT06 dari datasheet, dengan terminal ID 123456789012345, yang dibahas di Part 1. Saya menguji program di atas melalui loopback di laptop dengan skenario berikut:

Skenario Hasil
Satu frame utuh Terbaca satu frame, 18 byte ✓
Frame dikirim terpotong dua tahap (sisanya 1 detik kemudian) Tetap tersusun jadi satu frame ✓
Dua frame dikirim dalam satu write Terpisah jadi dua frame ✓
Byte sampah (FF DE AD) sebelum frame Sampah di-skip, frame tetap terbaca ✓
20 koneksi konkuren, tiap koneksi kirim frame 20 frame terbaca tanpa race ✓
SIGTERM saat ada koneksi aktif Listener + koneksi ditutup, program keluar bersih ✓

Berikut output log dari saat server mulai hingga berhenti:

2026/09/12 20:25:31 listening on :5094
2026/09/12 20:25:32 connected: 127.0.0.1:45870
2026/09/12 20:25:32 frame from 127.0.0.1:45870: 78780D01012345678901234500018CDD0D0A (18 bytes)
2026/09/12 20:25:33 shutting down: menutup listener dan koneksi aktif
2026/09/12 20:25:33 bye

Catatan Sebelum Lanjut #

Listener ini sudah menerima dan menyusun frame, tapi belum membaca payload atau membalas ACK. Tanpa ACK, device sungguhan mengira server tidak merespons dan terus mengirim ulang paket lama. Dua-duanya butuh CRC-ITU dan pemahaman struktur payload GT06.

Selanjutnya #

Artikel ini bagian dari seri Membangun GPS Backend dari Nol.

Ngobrol #

Kalau ada yang mau didiskusikan soal listener GPS ini, hubungi saya lewat Contact. Kamu juga bisa subscribe RSS untuk mengikuti artikel berikutnya.